@davmash/bygone 0.9.8 → 0.10.0

package/docs/visual-walkthrough/create-demo.mjs

@@ -0,0 +1,57 @@
+// Original, deterministic public fixture used by the visual walkthrough.
+import { mkdirSync, writeFileSync, cpSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import path from 'node:path';
+const root = path.resolve(process.argv[2] || '/tmp/bygone-visual-demo');
+mkdirSync(root, { recursive: true });
+const repo = path.join(root, 'parcel');
+mkdirSync(repo);
+const git = (...args) => execFileSync('git', args, { cwd: repo, encoding: 'utf8' }).trim();
+git('init', '-b', 'main');
+git('config', 'user.name', 'Bygone Demo');
+git('config', 'user.email', 'demo@example.invalid');
+const versions = [
+`// Parcel — a small release planner\nexport function planRelease(packages) {\n  const plan = [];\n\n  for (const pkg of packages) {\n    plan.push({\n      name: pkg.name,\n      version: pkg.version,\n      publish: true,\n    });\n  }\n\n  return plan;\n}\n`,
+`// Parcel — a small release planner\nexport function planRelease(packages) {\n  const plan = [];\n\n  for (const pkg of packages) {\n    if (pkg.private) continue;\n\n    plan.push({\n      name: pkg.name,\n      version: pkg.version,\n      publish: true,\n    });\n  }\n\n  return plan;\n}\n`,
+`// Parcel — a small release planner\nexport function planRelease(packages, options = {}) {\n  const plan = [];\n  const dryRun = options.dryRun ?? true;\n\n  for (const pkg of packages) {\n    if (pkg.private) continue;\n\n    plan.push({\n      name: pkg.name,\n      version: pkg.version,\n      publish: !dryRun,\n    });\n  }\n\n  return plan;\n}\n`,
+`// Parcel — a small release planner\nexport function planRelease(packages, options = {}) {\n  const plan = [];\n  const dryRun = options.dryRun ?? true;\n\n  for (const pkg of packages) {\n    if (pkg.private) continue;\n    if (!pkg.version) {\n      throw new Error('A release needs a version');\n    }\n\n    plan.push({\n      name: pkg.name,\n      version: pkg.version,\n      publish: !dryRun,\n    });\n  }\n\n  return plan;\n}\n`,
+`// Parcel — a small release planner\nexport function planRelease(packages, options = {}) {\n  const plan = [];\n  const dryRun = options.dryRun ?? true;\n\n  for (const pkg of packages) {\n    if (pkg.private) continue;\n    if (!pkg.version) {\n      throw new Error('A release needs a version');\n    }\n\n    plan.push({\n      name: pkg.name,\n      version: pkg.version,\n      publish: !dryRun,\n      channel: options.channel ?? 'stable',\n    });\n  }\n\n  return plan.sort((a, b) => a.name.localeCompare(b.name));\n}\n`
+];
+const titles = ['Start the release planner', 'Skip private packages', 'Default to a safe dry run', 'Reject missing versions', 'Sort releases and name their channel'];
+const revisions = [];
+for (let i = 0; i < versions.length; i++) {
+  writeFileSync(path.join(repo, 'release.js'), versions[i]);
+  writeFileSync(path.join(repo, 'README.md'), `# Parcel\n\nA small release planner.\n\n${titles.slice(0, i + 1).map(t => `- ${t}`).join('\n')}\n`);
+  writeFileSync(path.join(repo, 'release.yaml'), `release:\n  channel: ${i === 4 ? 'stable' : 'preview'}\n  dryRun: ${i >= 2}\n  packages:\n    - name: parcel-core\n      version: 1.2.0\n    - name: parcel-cli\n      version: 1.2.0\n`);
+  if (i === 4) writeFileSync(path.join(repo, 'CHANGELOG.md'), '# Release 1.2\n\nSafe defaults, explicit channels, predictable ordering.\n');
+  git('add', '.');
+  execFileSync('git', ['commit', '-m', titles[i]], { cwd: repo, env: { ...process.env, GIT_AUTHOR_DATE: `2026-09-0${i+1}T12:00:00Z`, GIT_COMMITTER_DATE: `2026-09-0${i+1}T12:00:00Z` } });
+  revisions.push(git('rev-parse', 'HEAD'));
+  writeFileSync(path.join(root, `release-v${i+1}.js`), versions[i]);
+  if (i === 0 || i === 4) {
+    const dir = path.join(root, i === 0 ? 'before' : 'after');
+    mkdirSync(dir);
+    for (const file of git('ls-files').split('\n')) cpSync(path.join(repo, file), path.join(dir, file));
+  }
+}
+const source = {
+  version: 4, title: 'Ship a safer release plan', range: { base: revisions[0], head: revisions[4] },
+  anchors: {
+    dry: { file: 'release.js', revision: 'head', contains: '  const dryRun = options.dryRun ?? true;' },
+    private: { file: 'release.js', revision: 'head', contains: '    if (pkg.private) continue;' },
+    stable: { file: 'release.js', revision: 'head', contains: "      channel: options.channel ?? 'stable'," }
+  }, connections: [], chapters: [{ id: 'safety', title: 'Make the safe path the easy path', scenes: [{
+    id: 'planner', title: 'A release should be deliberate', summary: 'Parcel turns package metadata into a release plan. This change makes safety the default and keeps the result predictable.',
+    bullets: ['Preview before publishing.', 'Keep private packages out.', 'Name the release channel.'], tags: ['safety', 'release'], takeaway: 'A plan is inspectable before it becomes a publish operation.',
+    steps: [
+      { id: 'dry-run', title: 'Preview by default', body: 'Omitting options now creates a dry-run plan. Publishing requires an explicit choice, so a caller can inspect the same plan before allowing side effects.', focus: 'dry' },
+      { id: 'private-packages', title: 'Respect the package boundary', body: 'Private packages never enter the plan. Filtering at the boundary means every later stage can operate on publishable packages.', focus: 'private' },
+      { id: 'channel', title: 'Make the destination visible', body: 'Each entry carries its release channel. The default is stable; callers can choose another channel when preparing a preview.', focus: 'stable' }
+    ]
+  }] }]
+};
+writeFileSync(path.join(root, 'release.bygone'), JSON.stringify(source, null, 2) + '\n');
+writeFileSync(path.join(repo, 'release.bygone'), JSON.stringify(source, null, 2) + '\n');
+writeFileSync(path.join(root, 'fixture.json'), JSON.stringify({ root, repo, revisions }, null, 2));
+console.log(root);
+/* global process, console */

package/docs/visual-walkthrough/deconstructed-demo.bygone

@@ -0,0 +1,100 @@
+version: 4
+title: Explain persistent tour markers in conceptual stages
+range:
+  base: d040a442657547340e5fa4dcc58bfc0d233ab989
+  head: b05ecc2c8998aa7569934dc7914c2e9924f7d0be
+anchors:
+  annotations:
+    file: src/webviewMessages.ts
+    revision: head
+    contains: '    tourAnnotations?: Array<{'
+connections: []
+chapters:
+  - id: explanation-order
+    title: Synthetic explanation stages
+    scenes:
+      - id: persistent-markers
+        kind: deconstructed-diff
+        title: Separate persistent markers from active emphasis
+        summary: Reorder one real commit into synthetic cumulative stages for teaching.
+        bullets:
+          - The source contract first permits several annotations.
+          - The presenter then marks every anchor and identifies the active one.
+          - >-
+            The renderer finally separates persistent gutter markers from active
+            text emphasis.
+        tags:
+          - tours
+          - explanation
+          - synthetic
+        takeaway: These panels are explanation stages, not historical commits.
+        base: d040a442657547340e5fa4dcc58bfc0d233ab989
+        target: b05ecc2c8998aa7569934dc7914c2e9924f7d0be
+        stages:
+          - id: contract
+            title: Carry every anchor
+            narration: >-
+              Expand the host contract from one annotation to an active-marked
+              collection.
+            changes:
+              - file: src/webviewMessages.ts
+                hunks:
+                  - hunk-64e041c7407c
+                  - hunk-f81ce869a41a
+          - id: presentation
+            title: Build persistent and active annotations
+            narration: >-
+              The tour host emits all anchors for the file and marks the current
+              step active.
+            changes:
+              - file: web/host.js
+                hunks:
+                  - hunk-baa2982f00b2
+                  - hunk-a11ba6c61eab
+                  - hunk-c32fa33b08c9
+                  - hunk-3d642f820720
+                  - hunk-34282593627a
+          - id: rendering
+            title: Emphasize only the active anchor
+            narration: >-
+              The renderer gives every anchor a gutter decoration while
+              reserving the text class and reveal target for the active one.
+            changes:
+              - file: media/script.js
+                hunks:
+                  - hunk-7ab25ee9fe44
+                  - hunk-229ff9b95257
+                  - hunk-208bf1e2739a
+                  - hunk-195c64e7ce9d
+                  - hunk-ca648f8b7f6d
+                  - hunk-0a640980b9b7
+                  - hunk-d005d43f28c8
+                  - hunk-814c1fb6cdf3
+                  - hunk-208dd701b2db
+                  - hunk-cd8f327f0940
+                  - hunk-9f54024f461a
+                  - hunk-56e6f514f9ae
+                  - hunk-45626d68d23d
+              - file: test/runTests.js
+                hunks:
+                  - hunk-69f71617ff01
+                  - hunk-55f5ba472e6c
+        exclusions:
+          - file: web/web-host.js
+            reason: Generated browser bundle; the source host is assigned above.
+          - file: web/web-host.js.map
+            reason: Generated source map; it carries no independent product behavior.
+        stack:
+          - id: before
+            ref: d040a442657547340e5fa4dcc58bfc0d233ab989
+            label: Before annotations
+          - id: after
+            ref: b05ecc2c8998aa7569934dc7914c2e9924f7d0be
+            label: Persistent annotations
+        steps:
+          - id: annotations
+            title: Carry every anchor
+            body: >-
+              A collection of annotations lets the renderer keep context visible
+              while emphasizing the active passage.
+            focus: annotations

package/docs/visual-walkthrough/narrative.md

@@ -0,0 +1,134 @@
+# Bygone, one screen at a time
+
+Bygone connects three activities: comparing concrete files, investigating their
+history, and explaining what you found. This guide starts with the diff itself,
+then follows those activities through the shared window. Each stop pairs a real
+screenshot with a specific thing to notice. Screens are examples, not live
+controls; open the matching workflow to explore your own files.
+
+## Compare what is in front of you
+
+### Two files, one visual comparison
+
+Start with two files when you already know what belongs on each side. Blue
+regions connect corresponding changed text; green regions mark content present
+on only one side. The ribbons show where the regions meet across the gutter.
+Read the pane labels before interpreting the colors: a local file can be
+editable, while a historical snapshot is read-only. Change navigation moves
+between the interesting regions without requiring you to scan every line.
+
+### Keep more versions in view
+
+A comparison can contain more than two panels. Visible panels controls how
+many fit in the window, while the active adjacent pair determines the current
+diff. Choose a fixed density or Fit; a narrower window may show fewer panels.
+The numbered headers keep the sequence legible. Use this when two endpoints
+hide an intermediate version that matters to the explanation.
+
+### Start with the directory
+
+When you know the area but not the file, compare directories first. The
+inventory puts additions, deletions, and changed files together. Open a file to
+inspect its contents, then return to the directory. This keeps the question
+“which file matters?” separate from the closer reading of its lines.
+
+### Find without abandoning the comparison
+
+Search helps when you know a name or phrase but not its location. Choose the
+scope before interpreting the results: visible panes, all comparison panels, the
+current change set, and Git history answer different questions. A result takes you back to the
+matching evidence. Replacement is a separate operation and depends on whether
+the target is writable.
+
+## Ask how it got here
+
+### Begin with repository history
+
+Repository history combines file navigation with the commit axis. Here, the
+latest commit adds CHANGELOG.md: the earlier pane is explicitly absent. Files
+and Commits are two ways to choose your next question. Revision labels identify the
+snapshots being compared; commit-list selections are a draft until you apply
+them. The numbered badges show which revisions occupy the comparison panels.
+
+### Follow a file through real revisions
+
+File history brings that same timeline to one path. The panels show exact
+historical contents, making a changed line something you can place in time.
+History and Compare share the window controls. Use the file navigation to
+visit files changed by the selected comparison, and the change controls to
+move within the open file.
+
+### Review the shape of a branch
+
+A branch review starts with an overview of the committed range. Its suggested
+reading order helps you choose an entry point; the complete file list remains
+available. The range labels matter: this is a comparison of committed evidence,
+not an implicit inclusion of every local edit. Start broad, then drill into the
+files that explain the change.
+
+## Turn exploration into an explanation
+
+### Read the tour as a document
+
+A tour adds a written argument to the evidence. The outline groups chapters,
+scenes, and steps; the continuous narrative establishes the question before
+pointing at source. Scrolling the narrative advances the reading position.
+Scrolling the code lets you inspect the evidence without advancing the story.
+The Narration controls provide another way to follow the same explanation.
+
+### Keep the explanation beside its evidence
+
+A step brings a precise passage into focus. Its body should explain why those
+lines matter, rather than repeat their syntax. As you read farther into a
+scene, the scene heading can stay at the top; expand it to recover the overview.
+The narrative and evidence remain independently navigable.
+
+### Separate explanation stages from commits
+
+Deconstructed tours group changes into conceptual stages. These are explicitly
+labeled explanation stages, so they should not be read as a claim about the
+actual commit sequence. Historical tours and real revision stacks answer the
+chronological question. Choose the mode that matches the explanation you want
+to give, and keep its provenance visible.
+
+### Explore, then return to the story
+
+A tour is a route through the material, not a fence around it. Files opens the
+broader inventory; Commits exposes the available revisions. History and Compare
+let you investigate a question that the author did not anticipate. Return to
+tour restores the authored passage after that detour.
+
+### Write the tour with explicit evidence
+
+The missing-tour handoff supplies an editable prompt and authoring instructions.
+It does not call an AI service on your behalf. The authoring workflow remains
+file based: write a .bygone source, validate the anchors against the intended
+Git range, then compile or present it. Keeping the evidence explicit makes the
+tour inspectable and repeatable.
+
+## Take the work with you
+
+### Share a particular place or a portable view
+
+Heading links identify a particular place in the tour. This screenshot shows
+the other sharing route: an exported HTML document with Tour details expanded. Local desktop links still depend on the referenced repository and tour
+being available. An HTML export is the portable reading option: minimal exports
+keep the tour evidence, while full exports also include bounded history.
+The notice here identifies a minimal snapshot and an embedded viewer requiring
+no internet. Choose based on how much independent exploration the recipient
+needs; CDN-backed exports instead require internet for their pinned viewer.
+
+### Stay near the editor in VS Code
+
+The VS Code companion handles contextual file comparison and file history near
+the editor. Larger repository, directory, multi-panel, and authored-tour work
+can open in Desktop. This is a division of workflows across hosts, with the
+same visual diff language carrying between them.
+
+### Choose the launch that matches the question
+
+The CLI provides direct entry points: two paths for a comparison, --history for
+a file or directory, --git-diff for revisions, review for a branch, and present
+--tour for an authored document. The tour subcommands provide schema,
+validation, compilation, and export. Start with the smallest question you can
+name, then use the shared window to expand the investigation.

package/docs/visual-walkthrough/outline.md

@@ -0,0 +1,52 @@
+# A visual guide to Bygone
+
+Audience: someone opening Bygone for the first time, with enough detail for an
+existing user to discover the larger workflows. Screenshots show Bygone 0.9.9
+plus the image-step support added for this guide. This is a product walkthrough,
+not a review of the implementation commits.
+
+## 1. Compare what is in front of you
+
+1. Two files: read paired changes, additions, and connector ribbons.
+2. More than two versions: use the active pair and Visible panels together.
+3. Directories: start with the inventory, then drill into a changed file.
+4. Find: search the comparison without losing the current evidence.
+
+## 2. Ask how it got here
+
+5. Directory history: orient yourself with Files and Commits.
+6. File history: keep exact revisions visible while following one file.
+7. Branch review: use the overview to choose a reading order.
+
+## 3. Turn exploration into an explanation
+
+8. Read a tour: outline, continuous narrative, and corresponding evidence.
+9. Follow a step: source focus and the expandable sticky scene heading.
+10. Deconstructed mode: distinguish explanation stages from real commits.
+11. Leave and return: Files, Commits, History, Compare, and Return to tour.
+12. Author a tour: the editable handoff prompt and the CLI validation workflow.
+
+## 4. Take the work with you
+
+13. Share: document-section links and a portable HTML export.
+14. VS Code: contextual comparison near the editor, with desktop handoff.
+15. CLI: choose a launch form appropriate to the question.
+
+## Capture and assembly contract
+
+- Write the narrative before capturing; reconcile it against what each screen actually shows.
+- Use the same dark theme and consistent viewport where practical.
+- Capture real rendered Bygone UI; do not paint hypothetical controls into images.
+- Store the images here with capture provenance and reproducible commands.
+- Prefer surrounding prose to annotations that cover code or controls.
+- Commit screenshots before pinning their exact Git revision in the tour.
+- Display one screenshot per authored step, grouped by the four arcs above.
+- Validate, compile, inspect every image step, and test a portable HTML export.
+
+## Required product support
+
+Tour steps need an optional image attachment resolved from the pinned Git range.
+The compiler must embed PNG bytes so the compiled tour and HTML export retain the
+image without a working tree or external image server. The presenter should show
+the image in its evidence area, with accessible alternative text, and restore
+normal code evidence when navigating away. Reject unsupported or invalid assets.