@davmash/bygone 0.9.7 → 0.10.0

package/docs/present.md

@@ -16,10 +16,10 @@ source evidence while keeping the complete changed-file set available.
 
 The left navigator switches directly among **Tour**, **Files**, and **Commits**;
 only one of those lists is visible at a time. The Tour outline has independently
-collapsible chapters and scenes; selecting a title jumps to that reading stop
+collapsible chapters and scenes; selecting a title jumps to its reading stop
 without changing which sections are expanded.
 
-The reading panel flows continuously through the tour title, chapters, scene
+The reading panel flows continuously through the tour title, chapter previews, scene
 overviews, and steps. Scroll the narrative or use keyboard navigation to move
 through that order; the corresponding code evidence follows. Scrolling the code
 does not advance the narrative. Each scene overview is a distinct stop with its
@@ -27,6 +27,10 @@ supporting points and takeaway. Each step keeps a collapsed **Scene context**
 disclosure above its title and explanation. Expanding that disclosure does not
 move the reading position.
 
+Chapters without an authored `summary` remain navigation headings and are
+skipped as reading and narration stops. Selecting their heading or opening an
+older chapter link takes the reader to the first scene.
+
 A direct link to a step opens that step immediately. The header reports the
 current position as `Scene N of M · Step N of M`, or identifies the overview.
 The reading panel scrolls within a bounded area above the evidence; no Start,
@@ -54,16 +58,54 @@ code the author anchored; it does not measure your reading progress. The
 header shows your current step. Tour search is likewise disclosed on demand or
 opened by `Cmd/Ctrl+Shift+F`.
 
+Authored v5 tours can show their purpose, scope, and estimated reading time in
+**Tour details**. Expand **Assumed familiarity** for codebase and language
+experience, reading demand, and prerequisites. Audience details are optional
+and specific to each independently authored mode.
+
+The opening states the expected behavior and its important boundary; the
+conclusion summarizes what the evidence established and what remains unresolved.
+These are authored explanations to evaluate against the code and requirements.
+
+Use **Explain this** or **Question this change** while reading to capture a
+question with the active tour's opening, current passage, comparison, and focused
+evidence. Review the captured context, then **Copy request** and paste it into your coding agent.
+Nothing is sent automatically. If clipboard access fails, the request remains
+selectable for manual copying. The agent should investigate whether code,
+explanation, a design decision, missing evidence, or the viewer needs repair.
+
 Generated overview ranking is deterministic for the resolved Git object IDs.
 It never hides files and does not invent an entry point for a test-only,
 lockfile-only, binary, or generated-only change. Authored tours keep their
 authored first scene and order.
 
+For desktop section links and portable Minimal/Full HTML snapshots, see
+[Links and portable HTML tours](sharing-tours.md).
+
+Opening a version 1, 2, or 3 authored tour in Desktop offers **Convert and open
+copy** by default. This saves a v4 copy beside the original (for example,
+`demo.v4.bygone`) without overwriting either the original or an existing copy.
+Cancel leaves the current view unchanged. The same offer appears when selecting
+a tour for HTML export; browser uploads ask before converting and download a copy
+after opening it.
+
+Conversion preserves authored IDs and revision references, so section links keep
+their targets. Review notes become a **Legacy review notes** appendix in the last
+authored step or stage of each available tour. The appendix includes readable notes,
+recorded revision IDs, evidence references, and next checks. Unrecognized review
+fields are retained verbatim in the flow. Resolvable walkthrough references link back to their steps. The notes
+are labeled as imported, not revalidated against potentially moving branches.
+YAML comments and formatting are not copied. Conversion
+stops with a specific validation error if the tour needs manual changes, such as
+a v1 synthetic-only root scene without the real revision evidence required in v4.
+Noninteractive CLI validation and compilation continue to require a supported
+source; open retired v3 sources in Desktop to convert them first.
+
 ## Explore and follow tours
 
-Version 2 and 3 presentations expose **History**, **Compare**, and the available
+Version 2 and 4 presentations expose **History**, **Compare**, and the available
 authored tours as direct mode buttons.
-Independent Historical and Deconstructed tours require version 3:
+Independent Historical and Deconstructed tours require version 4:
 
 - **History** uses all commits reachable from the presentation's head, in stable
   topological order, including commits that did not change the current file.
@@ -77,22 +119,24 @@ Independent Historical and Deconstructed tours require version 3:
   the active revision with its parent or the review base.
 - **Compare** shows one panel per selected revision, oldest to newest, with a
   diff between each adjacent pair. The Commit navigator remains available for
-  editing a draft selection; **Update comparison** applies it. Activating a loaded revision focuses its
-  panel. **Compare selected** includes all changed files. Parent/base shortcuts
+  editing a draft selection; **Apply** updates the displayed comparison. It is
+  disabled when the selection already matches. Activating a loaded revision
+  focuses its panel. **Compare** includes all changed files. Parent/base shortcuts
   stay on the current file; **Show all changed files** expands the same range.
   **Final diff** selects the review base
   and head across all changed files.
 
 All modes share the expanded **Commits** navigator. Check two or more revisions,
-then choose **Compare selected** (or **Update comparison** in Compare).
+then choose **Compare** (or **Apply** in Compare).
 Checkboxes edit a shared draft without reloading panels or leaving the tour.
 Numbered badges and highlights identify loaded real revisions independently of
 that draft. A dot marks commits that changed the current file, following renames;
 the **Tour** tag identifies commits in the authored range. Synthetic explanation
 stages are not labeled as Git revisions. Parent/base revisions outside the
 commit list appear as labeled extra rows.
+The **Selection actions** (•••) menu holds the shortcuts and selection tools.
 **Clear selection** unchecks draft revisions without changing modes or panels;
-**Reset selection** selects the real revisions currently loaded in the workspace.
+**Select displayed revisions** selects the real revisions currently loaded in the workspace.
 
 - **Historical tour** explains actual revision states, including intermediate
   changes, updates, and reverts. It retains chapters, scenes, steps, and narration.
@@ -133,7 +177,7 @@ text is spoken so the highlighted sentence remains visible.
 - Existing Previous and Next controls move through the same scene/step order
   used by continuous narration.
 - Choose any device voice exposed by the browser and a speed from 0.75× to
-  1.5×. Bygone stores those preferences locally and returns to the system
+  2×. Bygone stores those preferences locally and returns to the system
   default if a selected voice disappears.
 - The visible sentence is highlighted while it is spoken. Pausing retains a
   distinct paused highlight without moving keyboard focus.
@@ -163,10 +207,9 @@ conversation. Those remain separate from the offline, device-first baseline.
 Tour content is read-only. Author or revise the YAML and recompile it rather
 than editing historical or synthetic panels in the presenter.
 
-Version 3 authored tours may expose a separate, read-only **Review notes** panel
-for evidence-linked concepts, boundaries, tradeoffs, and open questions. Scene
-and step narrative should still explain the implemented change and the tradeoffs
-supported by its evidence.
+Scene and step narrative explain the implemented change, concepts, boundaries,
+and tradeoffs beside their evidence. Label unresolved questions explicitly and
+state the next check that would resolve them.
 
 ## Authoring workflow
 
@@ -186,7 +229,7 @@ synthetic deconstructed stages.
 
 ### Directory evidence in an Overview
 
-In version 3, an authored scene can show a directory comparison in its Overview. Open a file
+In version 4, an authored scene can show a directory comparison in its Overview. Open a file
 to inspect the same comparison while keeping the overview text, narration, and
 reading position. The **Overview** breadcrumb returns to its file tree;
 scroll through the narrative or select a step in the outline to continue the
@@ -200,3 +243,49 @@ Walkthrough scenes use the review's base-to-head comparison and the tour files,
 retaining omitted-file entries. Any scene type can limit the overview to a
 subdirectory. While browsing a file, `Overview › file path` shows where you are,
 with a reminder that narration still describes the overview.
+
+## Screenshot evidence
+
+A walkthrough step can display a committed PNG in place of its code comparison:
+
+```yaml
+- id: compare-window
+  title: Read the comparison
+  body: Blue regions pair corresponding changes across the gutter.
+  focus: guide-paragraph
+  image:
+    file: docs/images/comparison.png
+    revision: head
+    alt: Two code panes with blue paired changes and green additions.
+```
+
+The required `focus` still anchors the explanation to text in the tour's Git
+range. `image.revision` selects the comparison's merge base (`base`) or head
+(`head`). Compilation reads that Git blob, ignoring working-tree edits, and
+embeds its bytes in the manifest and HTML exports. Use repository-relative paths
+and meaningful alt text. PNGs are limited to 8 MiB, 16,384 pixels per dimension,
+and 64 megapixels. **Expand image** opens an enlarged view; Escape closes it.
+Returning to a code step, file, or comparison restores the regular workspace.
+
+Tours made entirely of image steps start on Intro with a route through their
+scenes. Next/Previous visits Intro, image steps, and the conclusion when authored,
+skipping chapter and scene headings. Selecting a chapter or scene displays its
+first image. The Intro outline entry returns to the route. Mixed code/image tours
+retain scene introductions. Intro and Conclusion use the full reading area;
+entering evidence restores the saved prose/code split.
+
+See the [visual walkthrough](visual-walkthrough/README.md) for a complete example.
+
+
+The Intro explains what the change does and gives a short route through the
+chapters. Chapters group related questions, scenes explain one question, and
+steps connect claims to evidence. Chapter, scene, and step lists use simple
+numbers for reference; reading headings and narration use plain titles.
+
+Chapter introductions show a brief authored preview and links to their scenes;
+narration reads the preview rather than the list of scene titles. The main explanation keeps the reasons
+for the change beside its evidence. Comparison captions identify the displayed
+revisions or constructed stages; a chapter or scene boundary does not itself
+mean the comparison changed. Intro, chapter, and Conclusion passages fill the
+reading area. Exploring Files restores the prose/code split, and “Return to
+passage” restores the full-height passage.

package/docs/product-surface.md

@@ -23,9 +23,15 @@ renderer does not make every workflow appropriate in every host.
 
 ## Shared workspace
 
+Window typography and chrome colors live in `media/windowTheme.css`, bundled
+into the shared renderer for Desktop, browser tours, HTML exports, and VS Code.
+Tour presentation styles consume those tokens rather than owning a separate
+palette. UI text uses the system sans-serif font; source code keeps its editor
+font. VS Code supplies its host theme and font through the existing variables.
+
 Desktop Explore uses **History · Compare · Historical tour · Deconstructed
-tour** without requiring an authored document. Missing tour buttons open an
-short, editable prompt referencing the bundled v3 tour skill and the workspace's
+tour** without requiring an authored document. Missing tour buttons open a
+short, editable prompt requesting a v5 tour and referencing the bundled skill and the workspace's
 repository, revisions, and selected paths. Read instructions exposes the Markdown;
 Save an editable copy and Use my copy support user-owned forks. Desktop prompts
 reference a real filesystem path outside the application archive. Browser prompts
@@ -36,14 +42,14 @@ when the selected instructions change. No model request or shell command runs
 automatically. Prompt ranges use exact committed identities or explicitly ask for
 a range choice. Existing tour loading remains available.
 
-**Open in History** resolves the comparison's Git ownership and path scope.
+**History** resolves the comparison's Git ownership and path scope.
 Its commit axis includes the selected revisions and their ancestry, including
 commits that did not change the active file. File-change markers and numbered
 active panels are distinct from unapplied comparison checkboxes. Clear clears
 the draft without changing modes. History retains add/remove-panel controls.
-**Back to comparison** restores the originating ordered comparison and its
-navigation. Mode transitions use the native unsaved-edit guard; writable
-working files remain writable and explicit read-only launches stay read-only.
+**Compare** restores the retained comparison and its navigation. Mode transitions
+use the native unsaved-edit guard; writable working files remain writable and
+explicit read-only launches stay read-only.
 
 Opening an authored document from this workspace keeps the same native window.
 A different repository, range, or scoped context requires confirmation; the
@@ -72,6 +78,7 @@ prompt behavior, and the normal-mode controls.
 | Explore a branch change | Git → Review Branch Change; `bygone review` | Deterministic start-here overview plus the complete merge-base-to-tip inventory | Read-only review snapshots; attention is a reading-order hint, viewed state remains session-local, and dirty state is reported rather than included | Core | attention-model, branch comparison, review-path, and desktop menu tests |
 | Search comparison code | Edit → Find or Search Comparison | Active, visible, all loaded panels, unopened changed text snapshots, or one file's Git history | Search is read-only; history distinguishes content occurrence from introduction/removal; Replace requires the active writable model | Core | find, comparison-search, change-set-search, and history-search tests |
 | Search or safely replace in a filesystem tree | Edit → Search in Files; explicit directory root | System ripgrep 14+ with include/exclude, hidden, ignore, and result-limit controls | Search is read-only and cancellable; completed case-sensitive literal searches can build an exclusion-aware, revalidated, atomic replacement preview with guarded undo | Optional system capability | repository search/replace contracts, benchmark, and host-protocol tests |
+| Choose visible panel count | Visible panels: 2 / 3 / 4 / Fit | Equal-width textual revision panels; one active adjacent comparison | Saved locally; Fit has no count cap beyond available panels and readable width; narrower windows show fewer panels without overwriting the choice; visible Find searches the whole group | Core | focused-strip layout and native density smoke tests |
 | Move through a multi-panel comparison | Strip buttons, panel headers, gutters, wheel, or `Alt+Arrow` | Active panel and adjacent pair | Does not change source identity | Core | focused-strip controller and standalone smoke tests |
 | Search an authored tour | Presenter search or `Cmd/Ctrl+Shift+F` | Authored narrative plus compiled base/head code snapshots | Read-only; narrative hits navigate scenes/steps and code hits preserve Return to tour | Core | tour-search and presenter-host tests |
 
@@ -87,8 +94,7 @@ appear only when Electron is not packaged.
 | --- | --- | --- | --- | --- | --- |
 | Explain a branch automatically | Present → Present Current Branch or Present Branch or Ref; `bygone present` | Committed merge-base-to-tip range with a deterministic overview first scene and complete Files navigator | Read-only; authored tours retain their authored order | Core | attention-model, presentation launch, generated-tour, and desktop menu tests |
 | Open an authored walkthrough | Present → Open Authored Tour; `bygone present --tour`; VS Code hand-off | Manifest range, scene, step, exact source anchor | Read-only | Core | reproducible example and tour validation tests |
-| Read optional authored review notes | Browser or desktop Present shows an opt-in **Review notes** button when a v3 manifest includes `review` | `baseOid`/`headOid` pins and evidence links into the Final walkthrough | Immutable range; read-only panel; no scores or persisted reviewer state | Local prototype | `examples/bygone-history.bygone`, `test/reviewNotes.test.js`, and manual browser navigation check |
-| Assess authored tour coverage | Coverage indicators in the Present sidebar | Distinct hunks referenced by authored walkthrough anchors; v2/v3 Final walkthrough coverage remains separate from deconstructed Explanation assignment completeness | Read-only authoring diagnostics; generated tours have no authored coverage metric | Advanced authoring | v1/v2/v3 coverage and presenter-host tests |
+| Assess authored tour coverage | Coverage indicators in the Present sidebar | Distinct hunks referenced by authored walkthrough anchors; v2/v4 Final walkthrough coverage remains separate from deconstructed Explanation assignment completeness | Read-only authoring diagnostics; generated tours have no authored coverage metric | Advanced authoring | v1/v2/v4 coverage and presenter-host tests |
 | Listen to a generated or authored tour | Narrative Listen controls; Present → Listen to Tour | Existing manifest narrative segmented locally by scene/step and visible sentence | Read-only device TTS; voice/rate preferences remain local; continuous playback follows tour navigation and direct exploration pauses it | Core | narration model/controller and presenter-host tests |
 | Explain a real stack | `stacked-diff` scene | Exact real Git revisions per panel | Read-only | Advanced | `examples/stacked-diff.bygone` |
 | Explain a change in conceptual stages | `deconstructed-diff` scene | Explicitly labeled synthetic explanation stages backed by exact hunk IDs | Read-only | Advanced/experimental authoring | `examples/deconstructed-diff.bygone` |
@@ -139,6 +145,11 @@ VS Code's native Search rather than another bundled ripgrep process.
 
 ## Provenance and mutability vocabulary
 
+Two-panel comparisons show immutable status beside the file summary and the
+editing toggle in the existing controls row when editing is available. Read-only
+status does not reserve a separate toolbar row. Multi-panel comparisons retain
+their per-panel provenance, including mixed writable and snapshot panels.
+
 Use these labels consistently:
 
 - **Writable file:** filesystem content and a live `WORKTREE` column participating in dirty, undo,

package/docs/sharing-tours.md

@@ -0,0 +1,95 @@
+# Links and portable HTML tours
+
+## Local desktop links
+
+Each title, chapter, scene, and step has a chain icon beside its heading, shown
+on hover or keyboard focus (always visible on touch screens). In a saved local
+tour it copies a `bygone://open/v1` link to that document, authored mode, and
+section ID. Open it with the installed desktop app, or choose **File → Open
+Bygone Link from Clipboard**. Links require the repository at the same local
+path; they do not clone repositories or find another checkout automatically.
+Tours saved outside the repository are supported: their links include the
+tour's local file URL separately from the repository. The tour must remain at
+that path, but the original presentation server does not need to be running.
+
+These document links open the **current saved document**. A branch named in the
+document may have moved since the link was copied. Use an HTML export when the
+recipient must see a fixed snapshot. Missing documents, modes, or section IDs
+produce an error rather than choosing a different step. Tour format v3 is
+retired: remove its `review` block, set `version: 4`, and recompile.
+
+**File → Copy Local Comparison Link** copies a two-revision comparison using
+full commit IDs in panel order. These links preserve the evidence even when
+branches move. The URL also supports an optional repository-relative `file`,
+selected `revision`, and one-based `line`. Missing commits, files, or lines fail
+before replacing the current comparison. Links open comparisons read-only.
+
+The versioned URL fields are:
+
+- Common: `kind=tour|compare`, `repo=<local file URL>`.
+- Tour: `tour=<repository-relative document path or local file URL>`, `mode=historical|deconstructed`,
+  `part=title|chapter|scene|step`, and the matching `chapter`, `scene`, or
+  `scene` plus `step` IDs.
+- Comparison: two ordered `rev=<full commit ID>` fields, with optional `file`,
+  `revision`, and `line`. A line requires a file and selected revision.
+
+## Export a saved tour
+
+Choose **File → Export Tour as HTML…**, or run:
+
+```sh
+bygone tour export path/to/tour.bygone --output tour.html
+bygone tour export path/to/tour.bygone --output tour-full.html --profile full
+```
+
+Existing output files require `--overwrite`. Export reads the saved tour and
+committed Git evidence. It freezes referenced revisions once, packages all
+authored modes, and leaves the source file unchanged.
+
+| Profile | Included evidence | Exploration |
+| --- | --- | --- |
+| Minimal (default) | Authored modes and full files needed for the endpoint comparison | Tour navigation and fixed base → head comparison |
+| Full | Minimal plus a bounded Git commit graph and scoped file snapshots | Included history and comparisons among included revisions |
+
+Full includes the range's merge base, commits between it and the head, and
+explicitly referenced tour revisions. Its path scope includes changed paths,
+rename predecessors, and tour evidence paths. It preserves intermediate changes
+that were reverted before the head. This is a read-only, Git-derived snapshot,
+not a cloneable repository or an arbitrary Git command environment. Parents
+outside the included set are unavailable. History diffs use the first parent;
+comparisons use exact paths, so renames appear as deletion and addition.
+
+Both profiles can contain full surrounding and deleted source code. Full also
+includes commit authors and email addresses. Local repository bindings are
+removed, but authored prose and paths remain. Inspect the output before sharing.
+**Tour details** reports the packaged evidence and profile boundaries.
+
+Initial Full limits are 256 revisions, 4,096 paths, 2 MiB per text file, and
+64 KiB per line; the final HTML limit is 128 MiB. Binary/non-UTF-8 files,
+submodules, Git LFS objects, and oversized files have explicit omission reasons.
+Queries beyond the packaged scope fail rather than fetching replacement evidence.
+
+## Viewer and internet access
+
+The default embeds the viewer, styles, workers, licenses, and evidence in one
+HTML file. Open it directly in a browser; no Bygone installation or local server
+is required. Editing, local repository operations, and link previews are
+unavailable. Narration uses only locally available system voices.
+
+A smaller CDN variant can load viewer assets from an exact npm release on
+jsDelivr. Evidence still lives in the HTML. It displays an internet-required
+message and checks each asset against its build-time SHA-256 digest. There is no
+fallback to a newer runtime. The matching export-enabled npm release must be
+published first; ordinary exports do not assume that release exists.
+
+For a verified published build, opt in with `--runtime cdn --runtime-base
+https://cdn.jsdelivr.net/npm/@davmash/bygone@<exact-version>/`. The version must
+match the exporting build. A missing, modified, or inaccessible asset produces a
+loading error; an embedded export avoids that network dependency.
+
+**Copy link** inside an export copies a browser URL with a semantic fragment.
+Share the HTML separately. When the recipient stores it elsewhere, append the
+fragment (starting with `#location=1`) to their file or hosted URL. Title,
+chapter, scene, and step targets are mode-specific; unknown targets produce an
+error. Exported evidence has a content digest for corruption detection, not a
+digital signature or proof of authorship.

package/docs/visual-walkthrough/README.md

@@ -0,0 +1,89 @@
+# Bygone, one screen at a time
+
+A 15-screen guided tour of comparisons, multiple panels, directories, search,
+repository and file history, branch review, authored tours, explanation stages,
+exploration, authoring, sharing, VS Code, and the CLI.
+
+## Open the tour
+
+From this checkout, build and use its CLI so the new image-step renderer is
+available. The installed 0.9.9 release predates this feature.
+
+```sh
+npm run compile
+BYGONE_FORCE_BUNDLED=1 node bin/bygone.js present --tour docs/visual-walkthrough/walkthrough.bygone
+```
+
+The command opens a local browser presentation on **Two files, one visual
+comparison**. Read down the narrative or select each step in the outline;
+each step replaces the evidence area with its screenshot. Next/Previous moves
+through the 15 images, skipping the structural headings as separate stops.
+Chapter and scene links open their first image, without a file inventory.
+**Expand image** makes the screenshot larger; Escape closes it. The controls
+inside a screenshot are illustrative, not interactive.
+
+With this branch's build installed, the equivalent command is:
+
+```sh
+bygone -C /Users/davmash/code/bygone present --tour docs/visual-walkthrough/walkthrough.bygone
+```
+
+## Read or share without a presentation server
+
+The [narrative](narrative.md) is the complete prose. Browse the
+[screenshots](images/) alongside it, or export one portable HTML file:
+
+```sh
+node bin/bygone.js tour export docs/visual-walkthrough/walkthrough.bygone --output /tmp/bygone-visual-walkthrough.html --profile minimal --runtime embedded
+```
+
+Open that file in a browser. Its viewer and screenshots are embedded; it needs
+neither internet nor a local repository. Use a fresh output path or add
+`--overwrite` to regenerate it. Minimal is the useful default for this visual
+guide; full export adds repository history that the screenshots do not need.
+
+## Maintain the guide
+
+The [outline](outline.md) records the scope. The
+[capture record](captures.md) identifies the real UI state behind each image
+and explains how to regenerate the demonstration repository and desktop images.
+The prose was revised against the actual captures before building the tour.
+The screenshots are unannotated; the prose and alt text supply the callouts.
+
+`walkthrough.bygone` pins the image and prose commit, so later working-tree edits
+cannot silently change its evidence. To revise it:
+
+1. Edit the prose or recapture the images, inspect the results, and commit them.
+2. Set `head` in `build-tour.mjs` to that commit's full SHA. Keep the base before
+   the guide was added so its narrative anchors remain in the comparison.
+3. Run `node docs/visual-walkthrough/build-tour.mjs` from the repository root.
+4. Validate, compile, and inspect the presentation again:
+
+```sh
+node bin/bygone.js tour validate docs/visual-walkthrough/walkthrough.bygone
+node bin/bygone.js tour compile docs/visual-walkthrough/walkthrough.bygone --output /tmp/bygone-visual-walkthrough.json
+```
+
+The repository keeps the PNG originals and authored source. Compiled manifests
+and HTML duplicate the embedded images, so they are generated outside Git.
+
+## Verification
+
+Checked on macOS on 2026-10-06:
+
+- Validated and compiled the authored source: four arcs, 15 image steps.
+- Inspected every capture, then loaded all 15 steps in both the live presentation
+  and the generated embedded HTML. The minimal HTML is approximately 24 MB.
+- `npm test` passed, including the legacy suite and 136 Node tests.
+- `npm run test:export-smoke` passed for ordinary tours and image evidence in
+  both Minimal and Full exports, with network requests blocked. It checks image
+  decoding, enlargement, Escape, Files → Return to tour, and code/Compare recovery.
+- `npm run bundle:check` and `git diff --check` passed.
+- ESLint passed for 142 checkout files with `tsconfigRootDir` explicitly set to
+  this repository. Plain `npm run lint` encounters an unrelated nested worktree
+  with another ESLint configuration; that worktree was excluded from this check.
+
+Linux/Windows rendering, screen-reader interaction, and a packaged installation
+of the new image renderer were not tested. The installed VS Code companion was
+used for its screenshot; it was not rebuilt. The portable runtime was tested
+embedded, not against a published CDN version.

package/docs/visual-walkthrough/build-tour.mjs

@@ -0,0 +1,54 @@
+// Rebuild prose from its pinned revision, never from an uncommitted draft.
+import fs from 'node:fs';
+import { execFileSync } from 'node:child_process';
+const base = 'e431a208f5ad24e3fae1a22300a14fc7d041375f';
+const head = '32bf8166cf6ae852fa801a540fe722b4070d5f4f';
+const folder = 'docs/visual-walkthrough';
+const prose = execFileSync('git', ['show', `${head}:${folder}/narrative.md`], { encoding: 'utf8' });
+const ids = ['two-files', 'many-panels', 'directories', 'search', 'repository-history', 'file-history', 'branch-review', 'tour-reader', 'focused-step', 'deconstructed', 'exploration', 'authoring', 'export', 'vscode', 'cli'];
+const alts = [
+  'Two JavaScript files with paired blue changes, green additions, and gutter ribbons connecting the regions.',
+  'Three of five JavaScript versions are visible, with Fit selected and the first adjacent pair active.',
+  'The before and after directory trees align three modified files and one added changelog.',
+  'A search for publish finds one result in each of the two visible comparison panes.',
+  'The commit navigator marks two loaded revisions; the comparison shows CHANGELOG.md added in the newest commit.',
+  'Two pinned release.js revisions show a new channel field and sorted return value beside the commit navigator.',
+  'The branch overview recommends starting with release.yaml, paying attention to release.js, and shows four changed files.',
+  'A tour outline and continuous narrative introduce a safer release plan above its changed-file overview.',
+  'The Preview by default step sits under a sticky scene heading and highlights the dry-run code evidence below.',
+  'Deconstructed tour stages show an explanation baseline beside the Carry every anchor stage, with focused TypeScript changes.',
+  'The Files navigator selects release.yaml while the authored narrative remains above; Return to tour is visible.',
+  'An authoring dialog contains an editable prompt, pinned review range, and a Read instructions button.',
+  'An exported tour has Tour details expanded: minimal snapshot, no browsable history, embedded viewer, no internet required.',
+  'VS Code hosts a read-only Bygone file history comparison next to the Explorer and source tabs.',
+  'A VS Code terminal displays the CLI usage forms for comparison, history, review, presentation, validation, compilation, and export.'
+];
+const summaries = [
+  'Start with concrete files. The same visual language scales from two versions to directories and search.',
+  'Add time to the comparison. Follow a path through commits or begin with the shape of a whole branch.',
+  'A tour turns findings into a reading path while leaving room for exploration.',
+  'Choose a sharing format and a host that fit the next reader’s question.'
+];
+let index = 0;
+const anchors = {};
+const chapters = prose.split(/^## /m).slice(1).map((chapter, c) => {
+  const [title, ...sections] = chapter.split(/^### /m);
+  const chapterTitle = title.trim();
+  const steps = sections.map(section => {
+    const newline = section.indexOf('\n');
+    const title = section.slice(0, newline).trim();
+    const body = section.slice(newline).trim().replace(/\n(?!\n)/g, ' ');
+    const id = ids[index];
+    anchors[id] = { file: `${folder}/narrative.md`, revision: 'head', contains: `### ${title}` };
+    const image = { file: `${folder}/images/${String(index + 1).padStart(2, '0')}-${id}.png`, revision: 'head', alt: alts[index] };
+    index++;
+    return { id, title, body, focus: id, depth: 'explained', image };
+  });
+  return { id: `chapter-${c + 1}`, title: chapterTitle, scenes: [{
+    id: `arc-${c + 1}`, title: chapterTitle, summary: summaries[c], bullets: [], tags: ['visual-guide'],
+    takeaway: summaries[c], steps
+  }] };
+});
+if (index !== 15) throw new Error(`Expected 15 images; found ${index}`);
+const tour = { version: 4, title: 'Bygone, one screen at a time', range: { base, head }, anchors, connections: [], chapters };
+fs.writeFileSync(`${folder}/walkthrough.bygone`, JSON.stringify(tour, null, 2) + '\n');

package/docs/visual-walkthrough/capture-desktop.cjs

@@ -0,0 +1,42 @@
+// Capture the real development app, optionally exercising its existing controls.
+// electron capture-desktop.cjs <output.png> <action> <Bygone arguments...>
+const { app, Menu } = require('electron');
+const fs = require('node:fs');
+const path = require('node:path');
+const [outputArg, action, ...args] = process.argv.slice(2);
+const root = path.resolve(__dirname, '../..');
+const output = path.resolve(outputArg);
+const cwdIndex = args.indexOf('-C');
+if (cwdIndex >= 0) { process.chdir(args[cwdIndex + 1]); args.splice(cwdIndex, 2); }
+app.setPath('userData', fs.mkdtempSync('/tmp/bygone-walkthrough-capture-'));
+process.argv = [process.argv[0], path.join(root, 'out/standalone-main.js'), '--window-width', '1440', '--window-height', '900', ...args];
+const delay = ms => new Promise(resolve => setTimeout(resolve, ms));
+const deadline = setTimeout(() => { console.error('Capture timed out'); app.exit(1); }, 60000);
+app.on('browser-window-created', (_event, win) => {
+  win.webContents.once('did-finish-load', async () => {
+    try {
+      await delay(3500);
+      if (action === 'find') {
+        const find = items => items.find(i => i.label === 'Search Comparison…') || items.flatMap(i => i.submenu ? [find(i.submenu.items)] : []).find(Boolean);
+        const item = find(Menu.getApplicationMenu().items);
+        if (!item) throw new Error('Search menu missing');
+        item.click();
+        await delay(500);
+        await win.webContents.executeJavaScript(`(() => { const el = document.querySelector('.visible-search-input'); if (!el) throw new Error('Search input missing'); el.value = 'publish'; el.dispatchEvent(new Event('input', {bubbles:true})); })()`);
+      } else if (action === 'fit') {
+        await win.webContents.executeJavaScript(`(() => { const el = document.querySelector('[data-multi-visible-count]'); if (!el) throw new Error('Density control missing'); el.value = 'fit'; el.dispatchEvent(new Event('change', {bubbles:true})); })()`);
+      } else if (action === 'older') {
+        await win.webContents.executeJavaScript(`document.querySelector('#history-back').click()`);
+      } else if (action === 'author') {
+        await win.webContents.executeJavaScript(`document.querySelector('[data-workspace-mode="historical"]').click()`);
+      }
+      await delay(1500);
+      fs.mkdirSync(path.dirname(output), { recursive: true });
+      fs.writeFileSync(output, (await win.webContents.capturePage()).toPNG());
+      clearTimeout(deadline);
+      console.log(`Wrote ${output}`);
+      app.exit(0);
+    } catch (error) { console.error(error); app.exit(1); }
+  });
+});
+require(path.join(root, 'out/standalone-main.js'));

package/docs/visual-walkthrough/capture-desktop.mjs

@@ -0,0 +1,21 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+const root = path.resolve(process.argv[2] || '/tmp/bygone-visual-demo');
+const { repo, revisions } = JSON.parse(fs.readFileSync(path.join(root, 'fixture.json')));
+const output = 'docs/visual-walkthrough/images';
+const captures = [
+  ['01-two-files', 'none', '--diff', `${root}/release-v1.js`, `${root}/release-v5.js`],
+  ['02-many-panels', 'fit', '--diff', ...[1,2,3,4,5].map(n => `${root}/release-v${n}.js`)],
+  ['03-directories', 'none', `${root}/before`, `${root}/after`],
+  ['04-search', 'find', '--diff', `${root}/release-v1.js`, `${root}/release-v5.js`],
+  ['05-repository-history', 'older', '--history', repo],
+  ['06-file-history', 'older', '--history', `${repo}/release.js`],
+  ['07-branch-review', 'none', '-C', repo, 'review', '--base', revisions[0]],
+  ['12-authoring', 'author', '-C', repo, 'review', '--base', revisions[0]],
+];
+for (const [name, action, ...args] of captures) {
+  const result = spawnSync('node', ['scripts/run-electron.mjs', 'docs/visual-walkthrough/capture-desktop.cjs', `${output}/${name}.png`, action, ...args], { stdio: 'inherit' });
+  if (result.status !== 0) process.exit(result.status ?? 1);
+}
+/* global process */

package/docs/visual-walkthrough/captures.md

@@ -0,0 +1,49 @@
+# Capture record
+
+Captured on macOS on 2026-10-06 from Bygone 0.9.9 (`e431a20`). The screenshots
+are unretouched. Desktop captures use a 1440 × 900 window and retain Retina
+resolution. Browser captures use a 1440 × 900 viewport, saved by the preview
+host at 1280 × 800. VS Code captures retain its existing 1229 × 768 window.
+The installed VS Code companion has different navigation chrome from Desktop;
+the guide deliberately shows that distinction.
+
+The small Parcel repository is original demonstration content, not a real
+customer or private codebase. Generate it in a fresh temporary directory:
+
+```sh
+node docs/visual-walkthrough/create-demo.mjs /tmp/bygone-visual-demo
+npm run compile
+node docs/visual-walkthrough/capture-desktop.mjs /tmp/bygone-visual-demo
+```
+
+The desktop harness launches an isolated development app, invokes real controls,
+and captures its web contents. Inspect regenerated captures before committing:
+loading delays and host differences can otherwise produce blank screenshots.
+
+| Image | Surface and capture state |
+| --- | --- |
+| 01 | Desktop: compare `release-v1.js` and `release-v5.js` |
+| 02 | Desktop: compare all five versions; choose Visible panels → Fit |
+| 03 | Desktop: compare the `before` and `after` directories (positional paths) |
+| 04 | Desktop: two-file comparison; Search Comparison → `publish`, Visible panes |
+| 05 | Desktop: repository history; Older commit once, showing added CHANGELOG |
+| 06 | Desktop: `release.js` history; Older commit once |
+| 07 | Desktop: review the fixture head against its first commit; Overview |
+| 08 | Browser: present fixture `release.bygone`; initial document/scene overview |
+| 09 | Browser: select Preview by default; scroll to the sticky scene heading |
+| 10 | Browser: present `deconstructed-demo.bygone`; select Carry every anchor |
+| 11 | Browser: from the fixture's first step, Files → release.yaml |
+| 12 | Desktop: branch review → Historical tour, opening the missing-tour prompt |
+| 13 | Browser: minimal embedded HTML export; first step; expand Tour details |
+| 14 | VS Code: `src/workspaceHistory.ts` → Bygone: View Active File History |
+| 15 | VS Code terminal: `node bin/bygone.js --help \| head -26` |
+
+For browser captures, start `require('./cli/present').startPresentation(args,
+repoRoot, process.cwd(), {open:false})` from Node in this checkout, then open the
+returned localhost URL. The fixture tour uses its Parcel repository; the
+checked-in deconstructed example uses this repository. Both contain pinned refs.
+
+The portable example was produced with `tour export` using `--profile minimal
+--runtime embedded`, then opened through a temporary static localhost server.
+No external image or content service supplied these screenshots. No image
+annotations were added: the guide's prose supplies the callouts.