@davmash/bygone 0.9.8 → 0.10.1

package/CHANGELOG.md

@@ -1,6 +1,31 @@
 # Changelog
 
-## Unreleased
+## 0.10.1
+
+- Fixed desktop tours showing unstyled HTML after temporary asset cleanup during long-running app sessions
+- Made presentation asset read failures return HTTP 500 and added HTTP and Electron ASAR regression coverage
+
+## 0.10.0
+
+- Restored detailed highlighting for long prose and expanded instructions; unavailable word detail now has a uniform blue fill and an explanatory `≠` marker
+- Made line-ending and final-newline differences visible instead of reporting identical files
+- Unified overlapping multi-panel highlights without stacked fills, with optional focus on the selected comparison pair
+- Added comparison-panel reordering, reliable revision selection, separate windows for new comparisons, and preserved initial change reveal
+- Added file trees and changed-file filters across views, plus single-file and blank-panel comparisons
+- Added portable HTML tour exports, pinned screenshot evidence, clearer tour introductions and navigation, and explanation expectations and reader feedback
+- Added 2x narration playback and stabilized expanded playback controls
+- Improved long-line and rewrapped YAML matching, with independent field-prefix scoring and ambiguity checks
+- Merged touching blue change regions while preserving scroll anchors, and clipped gutter connectors to editor bounds
+- Added desktop section links for tours saved outside their repository
+- Replaced repeated Scene context with clickable sticky scene headings and expandable overviews
+- Made History file navigation skip unchanged files; unified workspace controls, Files/Commits navigation, and disabled Tour tabs outside tours
+- Added saved 2/3/4/Fit panel density, uncapped Fit, stable visible groups, broader Find, and preserved edits and scroll positions
+- Unified window typography, surfaces, and control colors across tours, History, and Compare
+- Added automatic `+dev.N` versions for uncommitted local rebuilds without consuming release patch numbers
+- Bumped the tour authoring and compiled format to v4 and removed Review Notes; legacy sources offer conversion with review notes preserved in the tour flow
+
+macOS desktop downloads are unsigned and not notarized. If Gatekeeper reports
+the app as damaged, run `xattr -cr /Applications/Bygone.app`, then reopen it.
 
 ## 0.9.8
 

package/README.md

@@ -22,7 +22,7 @@ Bygone is a VS Code extension and standalone desktop app for visual diff and fil
 
 - Editable two-way side-by-side diff view
 - Dynamic adjacent multi-panel diff view
-- Flowing connectors, block contours, and inline change highlighting
+- Flowing connectors, block contours, and [inline change highlighting](#change-blocks-and-inline-highlighting)
 - Git file history viewer with commit-by-commit navigation
 - Local branch-change exploration using merge-base-to-tip semantics and changed-file progress
 - Binary-aware comparisons with side-by-side image previews and byte-equality reporting
@@ -31,6 +31,66 @@ Bygone is a VS Code extension and standalone desktop app for visual diff and fil
 
 This project is usable as a VS Code extension and standalone desktop app. The two-way diff and git history flows are the most complete. The multi-panel view is diff-focused, not a merge tool.
 
+## Change blocks and inline highlighting
+
+Hover a changed block on either side or its gutter connector to show copy arrows.
+Moving the text cursor into a changed block or jumping to a change also shows them.
+Each arrow stays beside its source block's first line: the left arrow points right,
+and the right arrow points left. Clicking copies that block to the opposite panel;
+arrows targeting a read-only panel are disabled.
+
+A touching run of deletions and insertions forms one blue replacement block,
+even when the text has no matching words. One-sided changes stay green. Green
+and blue blocks can still touch; exactly matching lines separate change regions.
+When an unpaired gap contains exactly one line on each side, those lines are
+compared for inline highlighting. Larger ambiguous gaps keep conservative line
+alignment within their blue block. A short statement expanded from one line to
+several, or collapsed back to one, is compared as a whole for inline highlights
+when the combined text is similar enough. This preserves the line alignment and
+the inline highlighting length limit.
+
+Multi-panel comparisons show changes from all adjacent pairs. A shared panel
+shows the union of changed lines and words, with overlaps painted once. A line
+that is one-sided in one pair and replaced in another uses replacement blue;
+connectors in each gutter still describe that pair. **Focus selected pair** is off
+by default. Turn it on to show only the selected pair's highlights and connectors,
+then select another gutter to inspect that comparison with its own block colors.
+Toggling focus preserves your scroll position. Previous/next change always follows the selected pair.
+Directory and file views share the **Visible panels** setting (2, 3, 4, or Fit),
+so opening a file or returning to its directory keeps the chosen density.
+New three-way and four-way comparisons start with 3 and 4 panels selected.
+Those counts stay visible even in tight windows; choose **Fit** for automatic
+width-based adjustment. You can still select a smaller count manually.
+
+Bygone matches words first, then uses **edge trimming** inside each replacement:
+leave the longest identical beginning and ending unhighlighted, and highlight
+the remaining middle. The beginning and ending never overlap. If one complete
+text is a prefix or suffix of the other, keep it unhighlighted: `Name` → `NewName`
+shows `Name` → `[New]Name`. If either edge works, or otherwise when matching edges
+overlap, prefer the beginning. Adjacent removed
+and inserted tokens form one replacement until an unchanged token separates them.
+
+Brackets below represent the stronger inline highlight:
+
+| Change | Highlighted result |
+| --- | --- |
+| `oldName` → `newName` | `[old]Name` → `[new]Name` |
+| `nameOld` → `nameNew` | `name[Old]` → `name[New]` |
+| `userCount` → `usersCount` | `userCount` → `user[s]Count` |
+| `userStatisticalCount` → `userMetricsCount` | `user[Statistical]Count` → `user[Metrics]Count` |
+| `oldNameOld` → `newNameNew` | `[oldNameOld]` → `[newNameNew]` |
+
+This handles a single contiguous edit anywhere in a replacement. It does not
+search for unchanged text inside the remaining middle: multiple separated edits
+within one word highlight everything from the first difference through the last.
+It also makes no semantic judgment: `timeoutMs` → `timeoutSeconds` preserves the
+shared final `s`, showing `timeout[M]s` → `timeout[Second]s`.
+
+Highlight boundaries preserve whole displayed Unicode characters, including
+combining accents and emoji. Edge trimming changes inline emphasis, not line
+pairing or block colors. Existing whitespace-only highlighting and limits on
+inline highlighting for long lines still apply.
+
 ## Install For Development
 
 Install dependencies and compile:
@@ -81,6 +141,19 @@ For a one-command local sync that builds the repo, installs the global CLI, pack
 npm run dev:sync
 ```
 
+A clean checkout installs the committed version. Rebuilding with uncommitted
+changes automatically increments a local iteration: `0.9.9+dev.1`,
+`0.9.9+dev.2`, and so on. The CLI, Desktop About dialog, and artifact names
+include that label. This is SemVer build metadata, not a new release patch;
+it does not change version precedence. `npm run reinstall` reuses the current
+artifacts without incrementing the iteration.
+
+For a real release, set the intended plain version with
+`npm version 0.9.10 --no-git-tag-version`, consolidate the changelog, and commit
+before `npm run dev:sync`. Local dev versions must not be published;
+`release:build` and `release:publish` reject them. Keep dev iterations out of
+committed release history.
+
 CLI defaults:
 - In a Git repo, `bygone` opens directory history for the current directory.
 - Outside a Git repo, `bygone` opens a blank editable diff.

package/cli/commandSpec.js

@@ -18,6 +18,8 @@ const CLI_SPEC = Object.freeze({
         'bygone tour compile <file.bygone> [--output <tour.json>]',
         'bygone tour context [<head>] [--base <base>] [--output <context.json>]',
         'bygone tour coverage <file.bygone> [--json] [--minimum-coverage <0-100>]',
+        'bygone tour export <file.bygone> --output <tour.html> [--profile minimal|full] [--runtime embedded|cdn]',
+        'bygone <bygone://open/v1?...>',
         'bygone tour schema',
         'bygone --branch-diff [-b BRANCH] [-m MAIN]',
         'bygone completion <zsh|bash|fish>',

package/cli/completions.js

@@ -75,7 +75,7 @@ ${legacyOptions}
 ${historyOptions}
     )
     shells=('zsh:Z shell' 'bash:Bash' 'fish:Fish shell')
-    tour_actions=('context:Build structured change evidence' 'coverage:Measure authored tour coverage' 'validate:Validate source and anchors' 'compile:Compile a repository-bound manifest' 'schema:Print the source schema')
+    tour_actions=('context:Build structured change evidence' 'coverage:Measure authored tour coverage' 'validate:Validate source and anchors' 'compile:Compile a repository-bound manifest' 'export:Export a portable HTML tour' 'schema:Print the source schema')
 
     if (( CURRENT == 2 )); then
         _describe 'bygone command' root_items
@@ -183,7 +183,7 @@ _bygone() {
             ;;
         tour)
             if (( COMP_CWORD == 2 )); then
-                COMPREPLY=( $(compgen -W 'context coverage validate compile schema' -- "$cur") )
+                COMPREPLY=( $(compgen -W 'context coverage validate compile export schema' -- "$cur") )
             elif [[ "\${COMP_WORDS[2]}" == "context" ]]; then
                 refs="$(_bygone_git_refs)"
                 if [[ "$prev" =~ ^(${baseTokens})$ ]]; then
@@ -262,7 +262,7 @@ function generateFishCompletion() {
 
     lines.push(
         "complete -c bygone -n '__fish_seen_subcommand_from completion' -a 'zsh bash fish' -d 'Shell'",
-        "complete -c bygone -n '__fish_seen_subcommand_from tour' -a 'context coverage validate compile schema' -d 'Tour action'",
+        "complete -c bygone -n '__fish_seen_subcommand_from tour' -a 'context coverage validate compile export schema' -d 'Tour action'",
         "complete -c bygone -n 'string match -q \"*tour context*\" -- (commandline -opc)' -l base -r -a '(__bygone_git_refs)' -d 'Set the change-context base ref'",
         "complete -c bygone -n 'string match -q \"*tour context*\" -- (commandline -opc)' -l output -s o -r -d 'Write the change context'",
         "complete -c bygone -n 'string match -q \"*tour context*\" -- (commandline -opc)' -l max-patch-bytes -r -d 'Maximum included patch size per file'",

package/cli/present.js

@@ -1,4 +1,4 @@
-const { createReadStream, existsSync, mkdirSync, readFileSync, writeFileSync } = require('fs');
+const { existsSync, mkdirSync, readFile, readFileSync, realpathSync, writeFileSync } = require('fs');
 const { createServer } = require('http');
 const path = require('path');
 const { spawn } = require('child_process');
@@ -6,8 +6,10 @@ const { buildChangeTourManifest, parseChangeTourStory } = require('../out/change
 const { buildTourAuthoringCoverage, buildTourCoverageReport } = require('../out/tourCoverage.js');
 const { buildTourWindowTitle } = require('../out/windowTitle.js');
 const { tokenMatches } = require('./commandSpec.js');
-const { loadTourSource, parseTourSourceText, buildManifestForTourSource } = require('./tourFile.js');
+const { loadTourSource, parseTourSourceText, inspectTourConversion, convertTourSourceText, buildManifestForTourSource } = require('./tourFile.js');
 const { createTourHistory } = require('./tourHistory.js');
+const { pathToFileURL } = require('url');
+const { resolveDocumentFocus, serializeDocumentFragment } = require('../out/deepLink.js');
 
 const MIME_TYPES = new Map([
     ['.css', 'text/css; charset=utf-8'],
@@ -24,7 +26,9 @@ async function startPresentation(args, cwd, packageRoot, options = {}) {
     const story = !options.ignoreEnvironment && process.env.BYGONE_TOUR_STORY
         ? parseChangeTourStory(JSON.parse(readFileSync(path.resolve(cwd, process.env.BYGONE_TOUR_STORY), 'utf8')))
         : undefined;
-    const source = tourPath ? loadTourSource(cwd, tourPath).source : undefined;
+    const loadedSource = tourPath ? await (options.loadTourSource || loadTourSource)(cwd, tourPath) : undefined;
+    if (tourPath && !loadedSource) return null;
+    const source = loadedSource?.source;
     const builtManifest = buildChangeTourManifest(cwd, {
         headRef: explicitHeadRef || source?.range?.head || headRef,
         baseRef: baseRef || source?.range?.base,
@@ -36,6 +40,14 @@ async function startPresentation(args, cwd, packageRoot, options = {}) {
     const manifest = source
         ? { ...builtManifest, authoringCoverage: buildTourAuthoringCoverage(buildTourCoverageReport(cwd, source)) }
         : builtManifest;
+    if (options.location) resolveDocumentFocus(manifest, options.location.mode, options.location.focus);
+    if (tourPath) {
+        const root = realpathSync(builtManifest.repository?.root || cwd);
+        const documentPath = realpathSync(loadedSource.resolvedPath);
+        const relative = path.relative(root, documentPath).split(path.sep).join('/');
+        const contained = relative && relative !== '..' && !relative.startsWith('../') && !path.isAbsolute(relative);
+        manifest.localSource = { repo: pathToFileURL(root).href, tour: contained ? relative : pathToFileURL(documentPath).href };
+    }
     const history = createTourHistory(manifest);
     const serializedManifest = `${JSON.stringify(manifest, null, 2)}\n`;
     const outputPath = options.ignoreEnvironment ? undefined : process.env.BYGONE_TOUR_OUTPUT;
@@ -68,16 +80,20 @@ async function startPresentation(args, cwd, packageRoot, options = {}) {
             request.on('end', () => {
                 if (response.writableEnded) return;
                 try {
-                    const uploadedSource = parseTourSourceText(JSON.parse(body).source);
+                    const input = JSON.parse(body);
+                    const conversion = inspectTourConversion(input.source);
+                    if (conversion && input.convertToV4 !== true) return respondJson(response, 409, { conversion });
+                    const converted = conversion ? convertTourSourceText(input.source) : null;
+                    const uploadedSource = converted?.source || parseTourSourceText(input.source);
                     const loaded = buildManifestForTourSource(cwd, uploadedSource);
                     const id = String(uploadedTours.size + 1);
                     uploadedTours.set(id, { manifest: loaded, history: createTourHistory(loaded) });
-                    respondJson(response, 200, { manifestUrl: `/loaded/${id}/tour.json`, repository: loaded.repository?.root || cwd, range: loaded.range });
+                    respondJson(response, 200, { manifestUrl: `/loaded/${id}/tour.json`, repository: loaded.repository?.root || cwd, range: loaded.range, convertedSource: converted?.text });
                 } catch (error) { respondJson(response, 400, { error: `Invalid tour for this repository: ${error.message}` }); }
             });
             return;
         }
-        const loadedMatch = requestUrl.pathname.match(/^\/loaded\/(\d+)\/(tour\.json|history\/(?:list|diff|compare|compare-many|revisions))$/);
+        const loadedMatch = requestUrl.pathname.match(/^\/loaded\/(\d+)\/(tour\.json|history\/(?:list|diff|compare|compare-many|changed-files|revisions))$/);
         const loadedTour = loadedMatch ? uploadedTours.get(loadedMatch[1]) : null;
         if (loadedMatch && !loadedTour) return respondJson(response, 404, { error: 'Loaded document not found' });
         if (loadedTour && loadedMatch[2] === 'tour.json') return respondJson(response, 200, loadedTour.manifest);
@@ -85,7 +101,7 @@ async function startPresentation(args, cwd, packageRoot, options = {}) {
         if (loadedMatch) requestUrl.pathname = `/${loadedMatch[2]}`;
         if (requestUrl.pathname === '/history/list' || requestUrl.pathname === '/history/diff'
             || requestUrl.pathname === '/history/compare' || requestUrl.pathname === '/history/compare-many'
-            || requestUrl.pathname === '/history/revisions') {
+            || requestUrl.pathname === '/history/changed-files' || requestUrl.pathname === '/history/revisions') {
             if (request.method !== 'POST') return respondJson(response, 405, { error: 'Method not allowed' });
             if (!isSameOriginLoopbackRequest(request)) return respondJson(response, 403, { error: 'Forbidden' });
             if (!requestHistory) return respondJson(response, 404, { error: 'History requires a version 2 tour.' });
@@ -110,7 +126,9 @@ async function startPresentation(args, cwd, packageRoot, options = {}) {
                                 ? requestHistory.compare(input)
                                 : requestUrl.pathname === '/history/compare-many'
                                     ? requestHistory.compareMany(input)
-                                    : requestHistory.revisions(input);
+                                    : requestUrl.pathname === '/history/changed-files'
+                                        ? requestHistory.changedFiles(input)
+                                        : requestHistory.revisions(input);
                     respondJson(response, 200, result);
                 } catch {
                     respondJson(response, 400, { error: 'Could not load history for this file and revision.' });
@@ -160,11 +178,20 @@ async function startPresentation(args, cwd, packageRoot, options = {}) {
             respond(response, 404, 'Not found');
             return;
         }
-        response.writeHead(200, {
-            'Content-Type': MIME_TYPES.get(path.extname(targetPath)) || 'application/octet-stream',
-            'Cache-Control': 'no-store'
+        // Electron streams extract ASAR entries to cached temporary files. Those
+        // can disappear during a long-running session; readFile reads the archive
+        // directly and lets us report failures before committing success headers.
+        readFile(targetPath, (error, content) => {
+            if (error) {
+                respond(response, 500, 'Read failed');
+                return;
+            }
+            response.writeHead(200, {
+                'Content-Type': MIME_TYPES.get(path.extname(targetPath)) || 'application/octet-stream',
+                'Cache-Control': 'no-store'
+            });
+            response.end(content);
         });
-        createReadStream(targetPath).on('error', () => respond(response, 500, 'Read failed')).pipe(response);
     });
     const requestedPort = readPort(options.ignoreEnvironment ? undefined : process.env.BYGONE_TOUR_PORT);
     await new Promise((resolve, reject) => {
@@ -176,7 +203,7 @@ async function startPresentation(args, cwd, packageRoot, options = {}) {
         server.close();
         throw new Error('Could not determine the presentation server address.');
     }
-    const url = `http://127.0.0.1:${address.port}/?manifest=/tour.json`;
+    const url = `http://127.0.0.1:${address.port}/?manifest=/tour.json${options.location ? serializeDocumentFragment(options.location.mode, options.location.focus) : ''}`;
     if (options.announce !== false) {
         process.stdout.write(`Bygone change tour running at ${url}\n`);
         process.stdout.write('Press Ctrl+C to stop.\n');
@@ -190,7 +217,7 @@ async function startPresentation(args, cwd, packageRoot, options = {}) {
             throw error;
         }
     }
-    return { manifest, server, url };
+    return { manifest, server, url, sourcePath: loadedSource?.resolvedPath };
 }
 
 function parsePresentArgs(args) {

package/cli/tour.js

@@ -4,9 +4,30 @@ const { buildChangeTourContext } = require('../out/changeTour.js');
 const { buildTourCoverageReport } = require('../out/tourCoverage.js');
 const { buildManifestForTourSource, loadTourSource } = require('./tourFile.js');
 
-const TOUR_ACTIONS = Object.freeze(['context', 'coverage', 'validate', 'compile', 'schema']);
+const TOUR_ACTIONS = Object.freeze(['context', 'coverage', 'validate', 'compile', 'export', 'schema']);
 
 function runTourCommand(args, cwd, packageRoot, output = process.stdout) {
+    if (args[0] === 'export') {
+        const { exportTour } = require('./tourExport');
+        let sourcePath, outputPath;
+        const options = {};
+        for (let i = 1; i < args.length; i++) {
+            const arg = args[i];
+            if (arg === '--overwrite') { options.overwrite = true; continue; }
+            if (['--output', '-o', '--profile', '--runtime', '--format', '--runtime-base'].includes(arg)) {
+                const value = args[++i];
+                if (!value || value.startsWith('--')) throw new Error(`${arg} requires a value.`);
+                if (arg === '--output' || arg === '-o') outputPath = value;
+                else if (arg === '--format') { if (value !== 'html') throw new Error('Only HTML export is supported.'); }
+                else options[arg === '--runtime-base' ? 'runtimeBase' : arg.slice(2)] = value;
+            } else if (arg.startsWith('-') || sourcePath) throw new Error(`Unexpected export argument: ${arg}`);
+            else sourcePath = arg;
+        }
+        if (!sourcePath || !outputPath) throw new Error('Usage: bygone tour export file.bygone --output tour.html [--profile minimal|full] [--runtime embedded|cdn]');
+        const result = exportTour(path.resolve(cwd, sourcePath), path.resolve(cwd, outputPath), packageRoot, options);
+        output.write(`Wrote ${result.profile} HTML tour to ${result.outputPath} (${result.bytes} bytes). ${result.summary}\n`);
+        return result;
+    }
     const options = parseTourArgs(args);
     if (options.action === 'schema') {
         output.write(readFileSync(path.join(packageRoot, 'schemas', 'change-tour-source.schema.json'), 'utf8'));

package/cli/tourExport.js

@@ -0,0 +1,147 @@
+const fs = require('fs');
+const path = require('path');
+const { createHash } = require('crypto');
+const { execFileSync } = require('child_process');
+const { TextDecoder } = require('util');
+const { buildManifestForTourSource, loadTourSource } = require('./tourFile');
+const { discoverAuthoredTourDocument } = require('../out/tourDocument');
+
+const ASSETS = ['web/presenter.css', 'media/webview.css', 'web/web-host.js', 'media/webview.js', 'media/editor.worker.js', 'media/diff.worker.js'];
+const MAX_BYTES = 128 * 1024 * 1024;
+function digest(value) { return createHash('sha256').update(value).digest('hex'); }
+function json(value) { return JSON.stringify(value).replace(/</g, '\\u003c').replace(/\u2028/g, '\\u2028').replace(/\u2029/g, '\\u2029'); }
+function html(value) { return String(value).replace(/[&<>"']/g, char => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[char])); }
+function git(root, args, binary = false) {
+    return execFileSync('git', args, { cwd: root, encoding: binary ? undefined : 'utf8', maxBuffer: MAX_BYTES, stdio: ['ignore', 'pipe', 'pipe'] });
+}
+function buildHistory(root, manifest, texts) {
+    const base = manifest.range.mergeBaseOid;
+    const head = manifest.range.headOid;
+    const refs = new Set([head, ...git(root, ['rev-list', '--topo-order', `${base}..${head}`, '--']).trim().split('\n').filter(Boolean), base]);
+    function collect(value) {
+        if (!value || typeof value !== 'object') return;
+        if (value.kind === 'stacked-diff') value.stack.forEach(panel => refs.add(panel.oid));
+        if (value.kind === 'deconstructed-diff') value.panels.forEach(panel => { if (panel.oid) refs.add(panel.oid); });
+        Object.values(value).forEach(child => { if (Array.isArray(child)) child.forEach(collect); else if (child && typeof child === 'object') collect(child); });
+    }
+    collect(manifest);
+    if (refs.size > 256) throw new Error('Full export exceeds the initial 256-revision safety limit. Narrow the tour range.');
+    const paths = new Set(manifest.files.flatMap(file => [file.path, file.previousPath].filter(Boolean)));
+    function collectPaths(value) {
+        if (!value || typeof value !== 'object') return;
+        if (typeof value.path === 'string' && value.kind !== 'directory-diff') paths.add(value.path);
+        Object.values(value).forEach(child => { if (Array.isArray(child)) child.forEach(collectPaths); else if (child && typeof child === 'object') collectPaths(child); });
+    }
+    collectPaths(manifest.scenes); collectPaths(manifest.tours); collectPaths(manifest.zoom);
+    const commits = [...refs].map(oid => {
+        const [parents, summary, timestamp, author, authorEmail] = git(root, ['show', '-s', '--format=%P%x00%s%x00%cI%x00%an%x00%ae', oid, '--']).trimEnd().split('\0');
+        const parentIds = parents.split(' ').filter(Boolean);
+        // Include changes that disappear in the final endpoint diff, and rename predecessors.
+        if (oid !== base) for (const name of git(root, ['diff-tree', '--root', '-m', '--no-commit-id', '-r', '--name-only', '-z', oid, '--']).split('\0').filter(Boolean)) paths.add(name);
+        return { oid, commit: oid, parents: parentIds, parentCommit: parentIds[0] || null, shortCommit: oid.slice(0, 7), summary, timestamp, author, authorEmail, message: summary };
+    });
+    if (paths.size > 4096) throw new Error('Full export exceeds the initial 4096-path safety limit. Narrow the tour.');
+    const snapshots = {};
+    for (const oid of refs) {
+        const tree = new Map(git(root, ['ls-tree', '-r', '-z', oid]).split('\0').filter(Boolean).map(record => {
+            const split = record.indexOf('\t');
+            const [mode, type, object] = record.slice(0, split).split(' ');
+            return [record.slice(split + 1), { mode, type, object }];
+        }));
+        snapshots[oid] = Object.create(null);
+        for (const name of paths) {
+            const record = tree.get(name);
+            if (!record) { snapshots[oid][name] = null; continue; }
+            if (record.type !== 'blob') { snapshots[oid][name] = { omitted: 'Submodule content is not packaged.' }; continue; }
+            if (Number(git(root, ['cat-file', '-s', record.object]).trim()) > 2 * 1024 * 1024) { snapshots[oid][name] = { omitted: 'File exceeds 2 MiB.' }; continue; }
+            const bytes = git(root, ['cat-file', 'blob', record.object], true);
+            let text;
+            try { text = new TextDecoder('utf-8', { fatal: true }).decode(bytes); if (bytes.includes(0)) throw new Error('binary'); }
+            catch { snapshots[oid][name] = { omitted: 'Binary or non-UTF-8 content.' }; continue; }
+            if (text.startsWith('version https://git-lfs.github.com/spec/v1\n')) { snapshots[oid][name] = { omitted: 'Git LFS object is not packaged.' }; continue; }
+            if (text.split('\n').some(line => Buffer.byteLength(line) > 64 * 1024)) { snapshots[oid][name] = { omitted: 'A line exceeds 64 KiB.' }; continue; }
+            const blob = digest(text); texts[blob] = text;
+            snapshots[oid][name] = { blob, mode: record.mode, gitBlob: record.object };
+        }
+        if (Buffer.byteLength(JSON.stringify(texts)) > MAX_BYTES) throw new Error('Export evidence exceeds 128 MiB. Narrow the tour.');
+    }
+    return { commits, paths: [...paths].sort(), snapshots, comparison: 'Exact paths; renames appear as deletion and addition. Parents outside the included set are unavailable.' };
+}
+function materializeTour(sourcePath, profile) {
+    const document = discoverAuthoredTourDocument(sourcePath);
+    const originalBytes = fs.readFileSync(document.documentPath);
+    const { source } = loadTourSource(document.repoRoot, document.documentPath);
+    const manifest = buildManifestForTourSource(document.repoRoot, source);
+    const texts = {};
+    const history = profile === 'full' ? buildHistory(document.repoRoot, manifest, texts) : undefined;
+    delete manifest.repository;
+    delete manifest.localSource;
+    // A source URL is optional provenance and may carry credentials or local bindings.
+    delete manifest.sourceUrl;
+    const contentKeys = new Set(['leftContent', 'rightContent', 'content']);
+    function pack(value) {
+        if (Array.isArray(value)) return value.map(pack);
+        if (!value || typeof value !== 'object') return value;
+        return Object.fromEntries(Object.entries(value).map(([key, child]) => {
+            if (contentKeys.has(key) && typeof child === 'string') {
+                const id = digest(child); texts[id] = child; return [key, { $text: id }];
+            }
+            return [key, pack(child)];
+        }));
+    }
+    if (!fs.readFileSync(document.documentPath).equals(originalBytes)) throw new Error('The tour source changed during export. Retry from the saved document.');
+    const packed = pack(manifest);
+    const identity = { profile, manifest: { ...packed, generatedAt: undefined }, texts, history };
+    return { version: 1, profile, contentId: digest(JSON.stringify(identity)), sourceFingerprint: digest(originalBytes), manifest: packed, texts, ...(history ? { history } : {}) };
+}
+function exportTour(sourcePath, outputPath, packageRoot, options = {}) {
+    const profile = options.profile || 'minimal';
+    const runtime = options.runtime || 'embedded';
+    if (!['minimal', 'full'].includes(profile)) throw new Error('Export profile must be minimal or full.');
+    if (!['embedded', 'cdn'].includes(runtime)) throw new Error('Export runtime must be embedded or cdn.');
+    const data = materializeTour(sourcePath, profile);
+    const version = JSON.parse(fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf8')).version;
+    const runtimeManifestPath = path.join(packageRoot, 'web', 'export-runtime.json');
+    if (!fs.existsSync(runtimeManifestPath)) throw new Error('Export runtime assets are missing. Rebuild Bygone first.');
+    const runtimeManifest = JSON.parse(fs.readFileSync(runtimeManifestPath, 'utf8'));
+    if (runtimeManifest.version !== version || runtimeManifest.schema !== 1) throw new Error('Export runtime does not match this Bygone build.');
+    if (runtime === 'cdn' && !options.runtimeBase) throw new Error('CDN export requires a published, verified export runtime. Use --runtime embedded until the export-enabled release is published.');
+    if (options.runtimeBase && !/^https:\/\/cdn\.jsdelivr\.net\/npm\/@davmash\/bygone@\d+\.\d+\.\d+(?:-[\w.-]+)?\/$/.test(options.runtimeBase)) throw new Error('Runtime base must pin an exact Bygone release on jsDelivr.');
+    if (runtime === 'cdn' && options.runtimeBase !== `https://cdn.jsdelivr.net/npm/@davmash/bygone@${version}/`) throw new Error('CDN runtime version must match this exact Bygone build.');
+    const assets = ASSETS.map(name => {
+        const bytes = fs.readFileSync(path.join(packageRoot, name));
+        const integrity = `sha256-${createHash('sha256').update(bytes).digest('base64')}`;
+        if (runtimeManifest.assets[name] !== integrity) throw new Error(`Runtime integrity mismatch: ${name}. Rebuild Bygone.`);
+        return { name, integrity, ...(runtime === 'embedded' ? { base64: bytes.toString('base64') } : { url: options.runtimeBase + name }) };
+    });
+    const payload = { ...data, runtimeVersion: version, assets };
+    const summary = `${profile === 'full' ? 'Full' : 'Minimal'} snapshot · ${Object.keys(data.texts).length} unique texts · ${Buffer.byteLength(JSON.stringify(data.texts))} evidence bytes${data.history ? ` · ${data.history.commits.length} revisions · ${data.history.paths.length} paths` : ' · no browsable Git history'}. Full file contents, including surrounding/deleted code, are included.`;
+    let shell = fs.readFileSync(path.join(packageRoot, 'web', 'index.html'), 'utf8')
+        .replace(/<link href="\/(?:media|web)\/[^"]+" rel="stylesheet">/g, '')
+        .replace(/<script src="\/(?:web|media)\/[^"]+"><\/script>/g, '')
+        .replace('<title>Bygone Tour</title>', `<title>${html(data.manifest.title)} — Bygone export</title>`);
+    const network = runtime === 'cdn' ? ' https://cdn.jsdelivr.net' : '';
+    const policy = `default-src 'none'; script-src 'unsafe-inline' blob:${network}; style-src 'unsafe-inline' blob:${network}; font-src data:; img-src data: blob:; worker-src blob:; connect-src${network || " 'none'"}; frame-src 'none'; base-uri 'none'; form-action 'none'`;
+    shell = shell.replace('<meta charset="UTF-8">', `<meta charset="UTF-8"><meta http-equiv="Content-Security-Policy" content="${policy}">`)
+        .replace('<body class="web-host">', `<body class="web-host"><div id="export-loading" role="status">Loading ${html(data.manifest.title)}… ${runtime === 'cdn' ? 'Internet required to load the Bygone viewer.' : 'Embedded viewer; no internet required.'} If loading fails, reopen the file or obtain a new export.</div><noscript>This interactive tour requires JavaScript.</noscript>`)
+        .replace('<summary>Tour details</summary>', `<summary>Tour details</summary><p class="export-notice">${html(summary)} ${runtime === 'cdn' ? 'Internet required to load the Bygone viewer.' : 'Embedded viewer; no internet required.'} ${html(data.history?.comparison || '')}</p>`);
+    const bootstrap = fs.readFileSync(path.join(packageRoot, 'web', 'export-bootstrap.js'), 'utf8');
+    const licenses = fs.readFileSync(path.join(packageRoot, 'web', 'export-licenses.txt'), 'utf8');
+    shell = shell.replace('</body>', `<script id="bygone-export-data" type="application/json">${json(payload)}</script><script>${bootstrap}</script><details class="export-notice"><summary>Runtime licenses</summary><pre>${html(licenses)}</pre></details></body>`);
+    if (Buffer.byteLength(shell) > MAX_BYTES) throw new Error('HTML export exceeds the 128 MiB safety limit. Narrow the tour.');
+    if (fs.existsSync(outputPath) && !options.overwrite) throw new Error('Output exists. Choose another path or pass --overwrite.');
+    if (path.resolve(sourcePath) === path.resolve(outputPath)
+        || (fs.existsSync(outputPath) && fs.realpathSync(sourcePath) === fs.realpathSync(outputPath))) throw new Error('Cannot overwrite the authored source.');
+    fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+    const temporary = `${outputPath}.${process.pid}.tmp`;
+    let created = false;
+    try {
+        fs.writeFileSync(temporary, shell, { flag: 'wx', mode: 0o600 });
+        created = true;
+        if (options.overwrite) fs.renameSync(temporary, outputPath);
+        else fs.linkSync(temporary, outputPath); // Fail atomically if another writer creates the destination.
+    }
+    finally { if (created) fs.rmSync(temporary, { force: true }); }
+    return { outputPath, contentId: data.contentId, profile, runtime, bytes: Buffer.byteLength(shell), summary };
+}
+module.exports = { exportTour, materializeTour, ASSETS };

package/cli/tourFile.js

@@ -1,7 +1,8 @@
 const { readFileSync, statSync } = require('fs');
 const path = require('path');
 const { TextDecoder } = require('util');
-const { loadAll: loadYamlDocuments } = require('js-yaml');
+const { loadAll: loadYamlDocuments, dump: dumpYaml } = require('js-yaml');
+const { serializeDocumentFragment } = require('../out/deepLink.js');
 const { buildChangeTourManifest, parseChangeTourSource } = require('../out/changeTour.js');
 
 const DEFAULT_MAX_TOUR_SOURCE_BYTES = 1024 * 1024;
@@ -13,6 +14,10 @@ function loadTourSource(cwd, sourcePath) {
 }
 
 function readTourSourceDocument(sourcePath, options = {}) {
+    return parseTourSourceText(readTourSourceText(sourcePath, options), path.resolve(sourcePath), options);
+}
+
+function readTourSourceText(sourcePath, options = {}) {
     const maxBytes = options.maxBytes ?? DEFAULT_MAX_TOUR_SOURCE_BYTES;
     if (!Number.isSafeInteger(maxBytes) || maxBytes < 1) {
         throw new Error('The Bygone source size limit must be a positive safe integer.');
@@ -48,10 +53,10 @@ function readTourSourceDocument(sourcePath, options = {}) {
         throw new Error(`Could not decode Bygone source ${sourceLabel} as UTF-8: ${errorMessage(error)}`, { cause: error });
     }
 
-    return parseTourSourceText(text, sourceLabel, { maxBytes });
+    return text;
 }
 
-function parseTourSourceText(text, sourceLabel = 'uploaded tour', options = {}) {
+function readTourSourceValue(text, sourceLabel = 'uploaded tour', options = {}) {
     const maxBytes = options.maxBytes ?? DEFAULT_MAX_TOUR_SOURCE_BYTES;
     if (typeof text !== 'string' || Buffer.byteLength(text, 'utf8') > maxBytes || text.includes('\0')) {
         throw new Error('Invalid tour text or source size limit exceeded.');
@@ -66,13 +71,110 @@ function parseTourSourceText(text, sourceLabel = 'uploaded tour', options = {})
         throw new Error(`Could not parse Bygone source ${sourceLabel}: expected one YAML document, found ${documents.length}.`);
     }
 
+    return documents[0];
+}
+
+function parseTourSourceText(text, sourceLabel = 'uploaded tour', options = {}) {
     try {
-        return parseChangeTourSource(documents[0]);
+        return parseChangeTourSource(readTourSourceValue(text, sourceLabel, options));
     } catch (error) {
         throw new Error(`Invalid Bygone source ${sourceLabel}: ${errorMessage(error)}`, { cause: error });
     }
 }
 
+// Inspect without accepting retired formats in the normal source parser.
+function inspectTourConversion(text, sourceLabel) {
+    const value = readTourSourceValue(text, sourceLabel);
+    if (![1, 2, 3].includes(value?.version)) return null;
+    return {
+        fromVersion: value.version,
+        preservesReview: Object.prototype.hasOwnProperty.call(value, 'review'),
+        message: `Convert this version ${value.version} tour to v4?`,
+        detail: 'Conversion preserves tour IDs and revision references. Review notes are preserved as a Legacy review notes appendix in the final authored step of each available tour. Their recorded revisions and evidence references are retained, without claiming they have been revalidated. The original file stays unchanged. YAML formatting and comments are not retained in the copy.'
+    };
+}
+
+function convertTourSourceText(text, sourceLabel) {
+    const conversion = inspectTourConversion(text, sourceLabel);
+    if (!conversion) throw new Error('Only authored tour versions 1, 2, and 3 can be converted to v4.');
+    const value = readTourSourceValue(text, sourceLabel);
+    const converted = { ...value, version: 4 };
+    delete converted.review;
+    try {
+        parseChangeTourSource(converted);
+        if (Object.prototype.hasOwnProperty.call(value, 'review')) appendLegacyReview(converted, value.review);
+        parseChangeTourSource(converted);
+    } catch (error) {
+        throw new Error(`This tour cannot be converted automatically to v4: ${errorMessage(error)} No evidence was changed; update the original tour manually.`, { cause: error });
+    }
+    const convertedText = dumpYaml(converted, { noRefs: true, lineWidth: -1 });
+    // Apply the same size and document checks to the serialized output.
+    const source = parseTourSourceText(convertedText, sourceLabel);
+    return { source, text: convertedText };
+}
+
+function appendLegacyReview(source, review) {
+    const modes = Object.entries(source.tours || {});
+    const evidenceLink = (evidence) => {
+        if (!evidence || typeof evidence.sceneId !== 'string' || typeof evidence.stepId !== 'string') return '';
+        const candidates = [...modes];
+        if (!source.tours?.historical) candidates.push(['historical', { chapters: source.chapters }]);
+        for (const [mode, tour] of candidates) {
+            const scene = tour.chapters.flatMap(chapter => chapter.scenes).find(scene => scene.id === evidence.sceneId);
+            if (scene && (!scene.kind || scene.kind === 'walkthrough') && scene.steps.some(step => step.id === evidence.stepId)) {
+                return ` [Open referenced step](${serializeDocumentFragment(mode, { part: 'step', scene: evidence.sceneId, step: evidence.stepId })})`;
+            }
+        }
+        return '';
+    };
+    let notes = '\n\n## Legacy review notes\n\nImported from the older tour. These notes have not been revalidated against the current revisions.';
+    // Render recognized review fields as ordinary prose. Keep unfamiliar or
+    // incomplete blocks verbatim so no legacy data is silently discarded.
+    if (review && typeof review === 'object' && Array.isArray(review.items)) {
+        notes += `\n\nRecorded revisions: ${review.baseOid ?? '(unspecified)'} → ${review.headOid ?? '(unspecified)'}.`;
+        for (const item of review.items) {
+            if (!item || typeof item !== 'object') continue;
+            notes += `\n\n### ${item.title ?? 'Review note'}\n\n${item.kind ?? 'Note'} (${item.id ?? 'no id'})\n\n${item.body ?? ''}`;
+            for (const evidence of Array.isArray(item.evidence) ? item.evidence : []) {
+                notes += `\n\nEvidence: ${evidence?.sceneId ?? '?'} / ${evidence?.stepId ?? '?'}.${evidenceLink(evidence)}`;
+            }
+            if (item.nextCheck !== undefined) notes += `\n\nNext check: ${item.nextCheck}`;
+        }
+    }
+    const onlyKeys = (value, keys) => value && typeof value === 'object' && !Array.isArray(value)
+        && Object.keys(value).every(key => keys.includes(key));
+    const recognized = onlyKeys(review, ['baseOid', 'headOid', 'items'])
+        && typeof review.baseOid === 'string' && typeof review.headOid === 'string'
+        && Array.isArray(review.items) && review.items.every(item =>
+            onlyKeys(item, ['id', 'kind', 'title', 'body', 'evidence', 'nextCheck'])
+            && ['id', 'kind', 'title', 'body'].every(key => typeof item[key] === 'string')
+            && (item.nextCheck === undefined || typeof item.nextCheck === 'string')
+            && Array.isArray(item.evidence) && item.evidence.every(evidence =>
+                onlyKeys(evidence, ['sceneId', 'stepId']) && typeof evidence.sceneId === 'string' && typeof evidence.stepId === 'string'));
+    if (!recognized) {
+        const raw = dumpYaml(review, { noRefs: true, lineWidth: -1 }).trimEnd();
+        const fence = '`'.repeat(Math.max(3, ...[...raw.matchAll(/`+/g)].map(match => match[0].length + 1)));
+        notes += `\n\n### Original review data\n\n${fence}yaml\n${raw}\n${fence}`;
+    }
+    const appended = new Set();
+    const append = (target, field) => {
+        if (!target || appended.has(target)) return;
+        target[field] += notes;
+        appended.add(target);
+    };
+    for (const tour of [{ chapters: source.chapters }, ...modes.map(([, tour]) => tour)]) {
+        const scene = tour.chapters.at(-1).scenes.at(-1);
+        if (scene.kind === 'deconstructed-diff') {
+            append(scene.stages.at(-1), 'narration');
+            // Legacy deconstruction also exposes its real-evidence steps in the
+            // Historical fallback. Preserve the notes there too.
+            append(scene.steps?.at(-1), 'body');
+        } else {
+            append(scene.steps.at(-1), 'body');
+        }
+    }
+}
+
 function errorMessage(error) {
     return error instanceof Error ? error.message : String(error);
 }
@@ -92,6 +194,9 @@ module.exports = {
     DEFAULT_MAX_TOUR_SOURCE_BYTES,
     buildManifestForTourSource,
     loadTourSource,
+    readTourSourceText,
+    inspectTourConversion,
+    convertTourSourceText,
     parseTourSourceText,
     readTourSourceDocument
 };