Field Instrument FI-155 :: v2.0.0
A local-first repair disassembly and reassembly instrument.
A repair rarely fails because the fault was hard to find. It fails because the information needed to put the object back together was destroyed on the way in. The screw that was a different length. The clip that faced the other way. The number on the adjuster before it moved. REPAIRMAP exists to hold that information while your hands are busy.
The central question it helps you answer:
Can this object be taken apart, repaired, and returned to service without losing the information needed to put it back together correctly?
REPAIRMAP is the repair-preservation sibling to PALIMPSEST (FI-113). PALIMPSEST exists to understand an unknown object. REPAIRMAP exists to return a known object to work.
Download repairmap-v2.0.0.html and double-click it. That is the whole install.
No server, no build step, no localhost, no account, no network. The file makes no requests of any kind. Everything you record stays in your browser on your machine.
Runs from file://. Also serves fine over http if you prefer, which is the
only way to guarantee photograph persistence (see Known Limitations).
SYMPTOM :: What the artifact does wrong, recorded before anything is opened. Multiple symptom records, each with a state (confirmed, intermittent, not reproduced, resolved, still present, unknown), plus an explicit hazard declaration before any powered testing.
ACCESS :: How the repair area will be reached. Multiple paths, compared side by side with risk, expected damage, time, tools and confidence. There is no score. The tradeoffs are shown and you select one.
DISASSEMBLE :: The teardown record. Nested and branching steps, before / during / after photographs, part removed, fasteners, connectors, cable routing, orientation, alignment marks, tool, resistance encountered, and the reassembly note that the reverse of the instruction does not capture. Steps can be reordered; the recorded order is preserved in the repair log.
INSPECT :: Findings, with observation and interpretation in separate fields. What you saw does not change when your theory does. Expected against actual, units, tolerance, severity, confidence, and a hypothesis field that is labelled as a hypothesis everywhere it appears.
REPAIR :: What was actually done. Eighteen actions including "no action required". Parts, suppliers, lot numbers, before and after condition, deviations from published procedure, and a temporary flag that follows the repair into the verification report and the final disposition.
REASSEMBLE :: The teardown read backward, corrected by hand. See below.
VERIFY :: Evidence that the original symptom is gone and nothing new arrived. Coverage is computed from the record: every symptom, every repaired component, safety functions on any declared hazard, and every temporary repair.
The signature feature. Any teardown step can carry flags.
Each flag sits on a four-band ladder, stated in words rather than as a score:
| Band | Reading |
|---|---|
| Reversible | Undone with the same hands and the same tools. |
| Reversible with consumables | Undone only if a replacement seal, adhesive or fastener is on hand. |
| Reversible with equipment or skill | Undone only with equipment or skill beyond this bench. |
| Irreversible | The artifact does not come back to as-found condition. |
and belongs to one of seven kinds:
- FASTENING :: one-use fasteners, rivets, crimps, staked nuts, seized threads
- BOND :: adhesive, tape, heat-staked posts, ultrasonic welds, solder, potting
- SEAL :: gaskets, o-rings, sealant beads, tamper and warranty seals
- SETTING :: calibration, alignment marks, shim stacks, spring preload, firmware
- ENERGY :: springs, gas struts, charged capacitors, pressure, fluids, suspended mass
- FORM :: parts that deform, fragile hidden clips, cosmetic surfaces, destructive access
- SUPPLY :: components consumed by opening and replaced rather than refitted
A flag is not a label. Every flag carries two obligations:
- a preservation prompt :: what must be captured before the step runs
- a requisition :: what must be in hand before the step runs
plus a field for the safer alternative access you considered, whether or not you took it. Write down the route you rejected. In six months the question is never whether, it is why.
Before an irreversible step is marked complete, a checkpoint asks whether the original condition is photographed, the settings are written down, the replacement material is identified, and the step is actually necessary. You can proceed without confirming all four. The repair log will record which ones you did not confirm, which is the point.
Under the station rail is a single line. It is not a progress bar and it does not report where you are in the application. It states, in words, what the artifact can still be returned to:
The artifact can still be returned to as-found condition.
The artifact returns to as-found only if the listed consumables are replaced.
The artifact no longer returns to as-found condition. Committed: Remove rear housing (Fragile hidden clip); Remove blade (Press-fit fan blade).
It moves when you acknowledge a flag, not when you click through stations. A ratchet turns one way, and so does a broken clip. Withdraw an acknowledgement and the reading falls back, because that is honest: nothing was actually committed.
The reassembly sequence is derived from the teardown map, but reversal is not a plan and the instrument does not pretend otherwise.
Generation carries forward:
- steps recorded as irreversible, with a note that reversing the step does not reverse the damage
- seals, adhesives, one-use fasteners and single-use supplies as consumable lines
- calibration and alignment settings as values to restore
- orientation, alignment marks and cable routing from the teardown record
Every step you edit is kept when the sequence is regenerated, and steps you add by hand survive regeneration untouched. Cure times, torque figures and the things that must go in before the cover closes belong to you, not to a generator.
Any teardown step that had substeps becomes a Closure Gate on the way back, because removing it is what granted access in the first place. The gate lists what the record says is unresolved (unfitted fasteners, one-use fasteners marked for reuse, findings with no disposition, missing photographs, unacknowledged flags, settings not recorded as set) and then asks the three questions only a person can answer:
- Nothing loose is left inside the assembly.
- No tools, offcuts or debris are inside.
- Required internal testing is done.
Signing a gate with items outstanding is allowed. The log records exactly what was outstanding and what you did not confirm.
Six, all reading the record rather than the artifact:
- Irreversibility check :: flagged steps without acknowledgement, without a requisition, or without a preservation prompt
- Photo coverage check :: completed steps with no photograph, flagged steps with no before photograph
- Fastener mismatch check :: groups with no destination, one-use fasteners marked for reuse, missing groups, and look-alike fasteners of different length or thread assigned to the same step
- Reassembly dependency check :: closures that happen ahead of work that still needs doing
- Closure gate :: gates marked done without being signed
- Verification coverage check :: symptoms, repaired systems and safety functions that are untested or not covered
There is no safe indicator. A clear check means the record is consistent, not that the repair is sound.
| Output | Formats |
|---|---|
| Repair evidence package | HTML (with or without photographs), JSON, print to PDF |
| Teardown map | SVG, PNG, JSON |
| Photo sequence | HTML, ZIP image package with an index |
| Fastener inventory | CSV, XLSX |
| Full record workbook | XLSX, seven sheets |
| Parts tray labels | SVG, printable label sheet, tray map CSV |
| Reassembly checklist | HTML, CSV |
| Verification report | HTML, JSON |
The evidence package is fourteen numbered sections plus a photo appendix and the full repair log. It opens with a note on how to read it: observation and hypothesis are separate fields and stay separate, a test with no result is reported as untested, and the document does not certify that the artifact is safe or fit for service.
Parts tray labels carry a QR code holding a plain-text reference internal to the project. Nothing in it reaches a network.
Every box is sized to hold its own label rather than truncating it, the tree is packed so that no two boxes overlap, and every edge runs through the empty gutter between two columns.
That last point is the design rather than a detail. Boxes live only in columns and edges live only in gutters, so an edge cannot cross a box. It is a property of the layout, not something tuned until it looked right, and the test suite walks every edge path point by point to prove it.
- Drag to pan, scroll or pinch to zoom, or press Fit.
- Collapse a branch with the circle on a step's edge, or by holding shift and clicking it. A collapsed step shows how many nodes it is holding.
- Arrow keys collapse and expand when a step has keyboard focus.
- Across or Down: the same tree laid out with depth running rightward or downward.
- The stripe on the left of a box is the highest irreversibility band recorded on that step.
Every change is checkpointed. Control or command with z steps back, and with shift steps forward. Typing into a field makes one checkpoint, not one per keystroke.
The repair log is deliberately left out of every checkpoint.
If you record a finding, change your mind and undo it, the finding leaves the record and the log keeps both the line that said you recorded it and a new line saying you took it back. A repair log that quietly loses the parts you regretted is a draft, not a record. The whole instrument exists to stop information going missing between the moment it was true and the moment you needed it, and its own history is not exempt from that.
Purging removed records is a barrier: undo cannot cross it, because purged photographs are genuinely gone and no checkpoint can bring them back. The History panel on the Data page lists every checkpoint and says which one you are standing on.
Nothing is destroyed when you remove a step, a finding, a fastener group, a photograph or a verification test. It moves into the project's removed records, whole, and a step takes its substeps with it so that putting it back puts the shape back. A removed record disappears from every view, every check and every report, but the repair log keeps the fact that it was removed and why.
Purging, on the Data page, is the only action in this instrument that cannot be undone. It is deliberately separate and asks twice.
A record restored after its parent has gone comes back at the top level, and the instrument tells you that is what it did rather than quietly filing it somewhere.
The search control in the top bar, or the slash key from anywhere, looks through every record in the project at once: teardown steps, the text inside irreversibility flags, fastener groups, findings, repairs, the reassembly sequence, verification tests, photograph captions and marks, journal entries, the log, and the removed records. Results are grouped by kind of record and choosing one takes you to it.
It reads what you wrote. It knows nothing about your artifact.
The fastener inventory exports as XLSX, and so does a seven sheet workbook of the whole record: fasteners, teardown, findings, repairs, reassembly, verification and the repair log.
A spreadsheet is a zip of xml parts, and the zip writer was already here for the photo package, so this file writes them itself. No library, no server, no conversion service.
Quantities are written as numbers so they can be summed. Anything with a leading zero stays text, because a part number, a lot code or a fastener code that comes back out of the spreadsheet renumbered is exactly the kind of quiet data loss this instrument exists to prevent.
A flag that says "photograph the connector orientation" is not much use if there is then no way to point at the connector. So a photograph can carry rotation, one rectangular crop, and three kinds of mark:
- a callout, a numbered circle on a thing
- an arrow, for which way it faces or which way it came out
- a region, ringing the area a note is about
Every mark is numbered in a single sequence, and a key underneath says what each number points at. A number with no key is decoration, so the editor says so when the key is empty.
Rotation, crop and marks are stored as numbers beside the photograph. The stored image is never modified. Reverting an annotation therefore cannot lose anything, because nothing was ever taken away.
Marks are held in the coordinates of the original, unrotated, uncropped frame, which is the only frame that does not move. Rotating or recropping carries every existing mark with it instead of scattering them across the picture.
Where a photograph is marked up, the exports carry both: the marked version to
read, and the untouched original as evidence. In the ZIP package the original
sits in an originals folder under the same sequence number, so anyone
reviewing the repair can check a mark against the frame the camera actually
produced.
The editor also shows you what the step's flags asked you to capture, so the preservation prompt and the photograph it was asking for end up in the same place.
REPAIRMAP is one HTML file. Opened from your disk it needs nothing installed, because the whole instrument is already in the file you double-clicked. Nothing below applies to that copy, and nothing below is ever required.
A copy served over http or https is a different situation: a browser cannot keep a hosted page without being told to. So when, and only when, the file is served, it adds an installable application with an offline cache.
- The app icon is a ratchet wheel and its pawl, drawn by code at whatever size the platform asks for, including a maskable variant with a proper safe zone. No image file is shipped.
- The manifest is generated at runtime and handed to the browser as a blob with the icons embedded. Nothing is fetched to build it.
- The offline cache holds the application file and nothing else. It never
caches, reads, uploads or transmits a repair record. Projects live in
localStorageandIndexedDB, neither of which the worker can see. - The cache name is stamped with the version it belongs to, and an older one is deleted when a new version activates.
A service worker cannot be registered from a file:// origin and cannot be
loaded from a blob. The platform requires it to be a separate same-origin
script. So sw.js sits beside the HTML on a server, and it is the only file
this project has that is not the instrument itself.
sw.js is optional and version agnostic. The page registers it with its own
version and document name in the query string, so one copy serves every
release. If it is missing, registration fails, the failure is caught, and the
instrument carries on exactly as it does from disk.
Because the whole application is one file, "a new version is available" means the cached file is about to be replaced by a different one. The service worker lifecycle is the wrong signal for that: by the time a new worker is waiting, the browser has usually already loaded the new file, so a prompt driven by it would offer you the version you are already running.
Instead the worker compares the version marker in the cached file against the one it just fetched, and only tells the page when they genuinely differ. You keep running the version you started, and a prompt names both versions and waits. Choosing Later leaves you exactly where you were. Choosing to reload saves the repair first, and writes the change into the repair log.
Updating never touches the record. Projects are in browser storage, not in the application file.
No device database. No torque specifications. No parts catalogue. No service manuals. No automatic flagging, no photograph recognition, no diagnosis.
REPAIRMAP will not tell you what is wrong with your artifact and does not conclude that anything is safe or fit for service. It is a record keeper for a person who is doing the repair.
- Text lives in
localStorage, photographs inIndexedDB, both per browser and per machine - Autosave with a visible saved / saving indicator
- Export a project with or without photographs, or a complete backup of everything
- Import validates against the schema and renders every field as inert text
- Archive, permanent delete with a typed confirmation, Clear Sample Data, and Clear All Local Data behind a second typed confirmation
Clearing site data deletes the repair. Export at the end of any session that mattered.
- 174 in-app assertions, green under jsdom and under Chromium loaded from
file://, with no console errors - 116 external harness checks covering every view, every export, project round
trip, blank-project hygiene, the closure gate, and source-level audits for
innerHTML,eval, network calls and em dashes - The QR encoder was compared module for module against an independent encoder. The first comparison mismatched on all eighteen payloads and caught two real defects: format information written least significant bit first, and missing version information blocks from version seven upward. After the fix, every payload where mask selection agrees is bit-identical, and all eighteen decode correctly through an independent decoder. Two golden vectors are held in the self test.
- The rasterised label sheet was scanned back with a real decoder at three resolutions, which is what caught a quiet zone that was two modules too narrow
- The ZIP writer was validated with an independent archive reader including CRC verification. SVG exports parse as XML and rasterise clean.
- 159 colour pairs checked numerically for WCAG contrast across all three themes, zero failures. The audit caught borders at 1.46 to 1 and forced a retune of the border, muted ink and active surface tokens.
- Layout measured in a real browser at 1500, 1100, 820 and 390 pixels wide with no horizontal overflow, and no interactive control under 44 pixels on a coarse pointer
- 49 further checks against a real browser and a real http server covering the
optional layer described below: worker registration, the generated manifest
and every icon decoded at its declared size, an offline reload with the
network switched off, a genuinely newer file producing the update prompt, the
record surviving the update, and the whole layer standing itself down on a
file://origin - 40 further checks on the map engine and undo in a real browser, including walking every edge path point by point to confirm none passes through a node box, a sixty step five level stress tree with no overlaps and no clipped labels, and a check that twenty one keystrokes make one checkpoint
- 33 further checks driving drag reorder, removal and restore, search, and the spreadsheet writer in a real browser, including unpacking the workbook and reading its parts back
- 48 further checks driving the annotation editor with a real pointer in a real browser: a click placing a callout and a drag placing an arrow at the coordinates they were made at, marks holding their place on the object across a rotation and a crop, the rasterised overlay changing the pixels under a mark and no others, and the exported original coming out byte for byte identical to what the camera produced
- PDF is produced through the browser print dialogue rather than a built-in writer, so pagination is the browser's. Every view carries a print stylesheet.
- Annotation covers rotation in quarter turns, one rectangular crop, and three kinds of mark. Freehand drawing, text placed directly on the image, blurring and straightening by an arbitrary angle are not in this release.
- A mark can be placed, renamed, renumbered or deleted, but not dragged to a new position afterwards. Delete it and place it again.
- The map lays the tree out in columns by depth. It does not reflow a very wide tree into a balanced shape, so a step with dozens of direct substeps makes one long column.
- Undo is a checkpoint of the record rather than a per-field edit history. Stepping back moves everything that changed since the last checkpoint, not one field at a time.
- Undo does not cross a purge, because purged photographs are genuinely gone.
- The QR encoder covers byte mode at error correction level M up to version ten. That is ample for a tray reference and is not a general purpose encoder. Mask selection evaluates the complete symbol, which is standard-conformant but can differ from encoders that evaluate with the format area blank. Both are valid and both decode.
- Some browsers refuse IndexedDB on a
file://origin. When that happens the Data page says so plainly and photographs are held in memory for the session only. Serving the file over http, or using a different browser, restores persistence. - Duplicating a project does not copy its photographs. They stay with the original, and the toast says so.
- Search is a plain substring match across the record. There is no fuzzy matching, no stemming, and no ranking beyond grouping by kind of record.
- Drag reorder covers the teardown tree. The reassembly sequence is ordered by the teardown and by hand editing, not by dragging.
- The XLSX writer emits values and a bold header row. It does not write formulas, number formats, merged cells or charts.
- The optional PWA layer needs
sw.jsbeside the HTML on a server. That is a platform requirement, not a choice, and it is the only sibling file in the project. The copy on your disk never uses it. - iOS has no installation prompt. Add to Home Screen from the share sheet is the only route, and it applies to a served copy rather than a local file.
- The offline cache is the application file only. Photographs are already held in browser storage and are unaffected either way.
1 to 7 jump to the stations. o overview, m map, p photos, f
fasteners, t trays, l log, k checks, r reports, ? help. / opens
search from anywhere, and control or command with z and shift z undo and
redo, including while you are typing. n adds a teardown step while you are on the Disassemble
station. Escape closes a dialogue. Shortcuts stand down while you are typing.
Drag reorder has a keyboard equivalent: the move controls in a step's menu do the same thing, so the teardown can be reordered without a pointer.
The About panel inside the instrument opens a message with the version string already in the subject line. Include what the instrument did that it should not have.
GPL-3.0
No third-party libraries. The QR encoder, the ZIP writer, the CRC, the Reed Solomon arithmetic and every reader and writer in this file were written for it. No fonts and no images are shipped; all artwork is inline SVG authored for this instrument, for a binary asset budget of zero bytes.