REGINGUIDE / VERSION 1.0.0
A guide for every
deliberate edition.
Author illustrated whole-kit instructions, account for every listed unit, and keep a released guide intact while you work on its revision.
ReginGuide records author acknowledgements. It does not validate assembly, safety, electrical suitability, geometry, or instruction completeness. Lantern Dial is fictional documentation with neutral original drawings, not a working circuit.
1. Open and make your first guide
Prerequisite: a desktop or laptop running Google Chrome, with permission to open local files and download ZIPs. This version was tested on Linux with Chrome 152.0.7977.82; other browsers and operating systems are unverified. No account, server, installation, or network connection is required.
- Extract the entire buyer ZIP into a normal folder. Open
app/index.html. Keep the app, manual and examples folders together. Do not try to run the HTML from inside an archive viewer. - Choose Try Lantern Dial example. The two steps already contain instructions, images and linked parts. Step S10 uses PCB1, R1, R2 and J1: four units. S20 uses H1 plus four S1 screws: five units. P1 is a spare knob: one unit.
- On Steps, read each step and check its author acknowledgement. On Review, read the coverage and check the whole-guide acknowledgement. Expected result: 10 total, 9 allocated, 1 spare, 0 items to resolve.
- Open Edition & export and choose Export draft guide ZIP. Extract this separate download and open its
index.htmlto see what a reader receives. - Choose Freeze released baseline, then Save project. Keep this editable project ZIP for the revision exercise below.
2. Bring your own parts table
Choose Create a guide on the opening screen. On Parts, set your title, hardware edition and guide edition. Then choose a .csv or .tsv file. The suffix selects comma or tab separation. Map each required field to one unique source column; optional columns can remain unmapped. Review the mapping and choose Use this parts table. Malformed input leaves the existing project intact.
| Field | Contract |
|---|---|
| part_id | Required exact, case-sensitive unique token, 1–64 characters, no whitespace, commas, < or >. Reserved IDs __proto__, constructor and prototype are rejected. No inferred renames. |
| description | Required nonempty plain text. Kept as supplied, including quotes and embedded newlines. |
| quantity | Required integer written as 0 or 1–9999. No signs, leading zeroes, decimals or units. |
| references | Optional comma-separated explicit tokens such as R1,R2. Each starts with a letter and contains only letters, digits, underscore or dot. No spaces or ranges. Token count must match quantity; references must be unique across the entire table. Quote a list in CSV. |
| value / footprint | Optional plain text shown in linked step tables. |
| dnp | Optional literal true, false or blank. Blank means false. DNP is never guessed. A true row must be explicitly excluded with a reason and cannot be allocated to a step. |
UTF-8 with or without a UTF-8 BOM; LF or CRLF lines. Quoted fields can contain delimiters, newlines and doubled quotation marks. TSV uses the same quoting convention with tabs as delimiters. Headers must be nonempty and unique; every record must have the same number of columns. Unsupported control characters are rejected. Unmapped source columns remain in the exact original source file but do not appear in the canonical BOM.
Use the included examples/Lantern-Dial-A.csv as a starter. Generic tables only: there is no verified KiCad, XLSX, PDF, native CAD or supplier-specific importer. The app cannot discover omitted source parts, substitute parts, expand ranges or infer renames. On Parts, Save original source retrieves the byte-identical imported table.
3. Write, illustrate and account
On Steps, add a step and enter its title and plain-text instructions. The app assigns an exact step ID. Use the up/down buttons to reorder steps with mouse or keyboard; Remove step deletes that step and its allocations. There is no undo, so save a project copy before major changes. Use Tab and Enter/Space to operate controls.
Search linked parts by ID, description, reference or value. A quantity of zero removes a link. The same part can be allocated to several steps as long as total consumed units plus dispositions equals its available quantity. Changing the source does not silently erase orphaned links; use Remove link to resolve a removed part deliberately.
Use Add image or Replace image for one PNG/JPEG per step. Dimensions are inspected before decoding, then the image is decoded and re-encoded as PNG. Add descriptive alt text (required when an image is present) and an optional caption. Output bytes change, embedded metadata is removed, and original image files are not retained in the project. Keep your own original images elsewhere. SVG, URLs, animated formats and other image types are not supported.
On Review, allocate leftovers as spare, preassembled or excluded. Enter units and a reason, then press Apply. A disposition may cover only the unallocated portion of a part. DNP and zero-quantity rows need an explicit excluded disposition and reason, even at zero units. Clear removes a disposition. Unassigned, overallocated, unknown and DNP-linked parts prevent recipient export.
Review every step and check its acknowledgement, then review all photos/prose/edition labels and check the whole-guide acknowledgement. Editing prose, image, caption, alt text or allocations revokes that step's acknowledgement. Changed linked parts revoke affected steps. Changing order or edition labels revokes all steps. Any content edit revokes whole-guide review; changing dispositions also revokes whole-guide review. These checks represent your acknowledgement only.
4. Keep A intact while repairing B
- Starting from the saved A project, ensure A is frozen as the released baseline. There is one immutable baseline per project; it cannot be replaced. Draft editing never mutates it.
- On Parts, choose Load fictional edition B table (example exercise only), or import
Lantern-Dial-B.csvnormally and set hardware B, guide 2 yourself. - B changes R2 to 22k, reduces S1 from four screws to three and adds W1, one washer. Initial B must report S1 overallocated by 1 and W1 unassigned 1. S10 and S20 require review. The final recipient export is blocked.
- Open S20 on Steps. Set S1 to 3 and W1 to 1. Review both steps and the whole guide. Expected B: 10 total / 9 allocated / 1 spare.
- Export B from the draft panel. Export A separately using Export released guide ZIP. A still contains R2=10k and four screws. B contains R2=22k, three screws and one washer. Save the project to keep both.
Replacement uses exact IDs, not guesses. Changed part dispositions are cleared so they can be reassessed. Unchanged parts cannot reveal geometry changes, which is why each edition also needs whole-guide photo/prose review. Use new hardware and/or guide labels for a changed edition. For a later independent lineage, save a backup and create a new project; v1 does not retain an unlimited release history or promote B over the frozen A baseline.
5. Save projects and share recipient guides
| Download | Purpose |
|---|---|
| Save project | Editable ReginGuide ZIP. Contains draft, optional released baseline, normalized images and exact source table bytes. Restore in the editor. Not a reader-facing guide. |
| Export draft / released guide ZIP | One explicit edition: static index.html, local images, BOM.csv, BOM-spreadsheet-safe.csv, step-parts.csv, source.csv/tsv, review.json and README. Readers do not need the paid editor. |
There is no autosave or cloud storage. “Unsaved changes” means you should download a project copy before closing. Save is enabled after a valid source table exists and can preserve unresolved allocations/reviews. Failed restores do not commit partial state. Restore accepts only intact ReginGuide project ZIPs with one uncompressed project.json entry. It rejects compressed, encrypted, multi-entry, nested-path, symlink, duplicate-entry and malformed archives. Do not unzip/recompress a project to edit it; use the editor.
Extract a recipient ZIP fully before opening index.html. Navigation links jump to steps. Use Chrome's Print command; select A4 or Letter and Save as PDF, with browser headers/footers disabled. Edition labels repeat in the print layout. Long instructions may span pages. Physical printing and identical pagination across browsers are not promised.
Canonical BOM.csv and original source preserve raw text, including formula-like values. For spreadsheet opening use the separately named BOM-spreadsheet-safe.csv, which prefixes an apostrophe when text starts with =, +, @ or - after whitespace. This variant changes those cell values; it is not the canonical source. Use a text reader when exact source text matters.
6. Supported bounds and tested scope
| Source table | 256 KiB, 100 part rows, 20 columns, 2,000 characters/cell. 1–64 character IDs, quantity 0–9999. |
|---|---|
| Authoring | 30 steps; title 120 characters; hardware/guide label 64; instructions 10,000 per step; alt text 300; caption/reason 1,000. |
| Images | One per step; input ≤2 MiB, ≤4,000,000 pixels. Normalized PNG payload ≤8 MiB across draft plus baseline; identical images in both editions count twice. No retained originals. |
| Editable archive | Project JSON ≤16 MiB; input ZIP ≤17 MiB. Exactly one stored project.json. Payload limits do not guarantee a particular browser RAM usage. |
| Verification | Linux Chrome, fresh offline contexts, actual local files; independent Python CSV arithmetic; Ghostscript PDF text/raster interpretation. Desktop and 390px layouts checked. Narrow layout is available, but desktop authoring is the tested primary workflow. |
These are bounded small-kit limits, not industrial-scale capacity claims. Native CAD integration, XLSX/PDF import, DOCX export, individual-reference consumption, real kit assembly, electrical correctness, physical printers and other browser/OS combinations are unverified or unsupported. No accessibility compliance certification is claimed.
7. Troubleshooting, privacy and removal
- The editor is blank or controls do not work: extract all files; open app/index.html in Chrome. Scripts must be allowed for local files. Do not move core.js/app.js away from index.html.
- Import rejected: use UTF-8, match every row's column count and quote embedded delimiters/newlines. Use unique headers/IDs/references, exact integers and literal DNP values. No source changes are made on failure.
- Export disabled: visit Review. Resolve every coverage item, fill required titles/instructions/image alt text, acknowledge each step, then the whole guide. Edits revoke acknowledgements by design.
- Image rejected: reduce dimensions/file size with your image editor, save PNG/JPEG, and retry. Reduce total normalized images before freezing a baseline. Baseline plus draft count toward the 8 MiB payload cap.
- Project will not restore: use the unchanged Save project ZIP, not a recipient ZIP or recompressed folder. Keep backup project copies. Never remove entries to bypass a validation error.
- A removed part is still shown: its step allocation is deliberately retained as an unknown link. Remove it explicitly and assign the correct part.
- Missing pictures in a recipient guide: extract the complete ZIP; keep index.html and images/ together.
- Downloads do not appear: check Chrome's downloads list and browser download permission. Download success means Chrome accepted the file; confirm it exists where you expect.
All processing is local. The app contains no network requests, telemetry, account integration, server or persistent browser database. Imported original files are only read. Downloads create new files and never overwrite sources silently. Sharing a project shares both source tables and all retained editions; share a recipient package when only one edition should be visible.
To uninstall, close the browser tab and delete the extracted editor folder. Delete downloaded projects/recipient ZIPs separately if desired. No service, extension or cloud account needs removal. Keep anything you want to retain before deleting it.
ReginGuide / Perunlight · Manual 1.0.0 · Screenshots use first-party fictional data. This manual and the free example pack contain no paid editor code.