@davmash/bygone 0.8.16 → 0.9.2

package/CHANGELOG.md

@@ -2,6 +2,36 @@
 
 ## Unreleased
 
+## 0.9.2
+
+- Documented the stable v3 tour contract, compatibility policy, and evidence-linked review notes
+- Updated Electron and vulnerable packaging dependencies within their existing major versions
+- Shared the expanded commit navigator across tours, History, and Compare, with explicit draft submission and loaded-panel badges
+- Kept History's commit axis and expanded panels stable across files, with markers for commits that changed the current file
+- Preserved navigator tabs and comparison drafts across mode switches
+- Replaced tour mode and comparison endpoint drop-downs with direct mode buttons and multi-select revision comparison
+- Added two-or-more-panel Compare views ordered from oldest to newest with adjacent diffs
+- Unified Present navigation into one Tour, Files, or Commits navigator
+- Made tours a continuous reading flow through title, chapters, scene overviews, and steps, with a collapsible outline and scene context above each step
+- Added shared workspace tour discovery, editable skill-based v3 authoring prompts, and same-repository transitions into History
+- Clarified tour mode restoration and directory overview scope while preserving first-visit History context
+
+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.1
+
+- Restored authored Final walkthroughs and legacy Final deep links for version 2 deconstructed tours
+- Reused the full revision rail and toolbar in tour History mode while preserving the selected file on first entry
+- Expanded Files and Tour details by default and kept Scene context available alongside the active step
+
+## 0.9.0
+
+- Added independently authored Historical and Deconstructed tours with stable per-mode reading positions
+- Added optional scene-level directory overviews with safe repository-relative scoping and authored comparison endpoints
+- Added evidence-linked review notes for concepts, boundaries, tradeoffs, and open questions
+- Introduced source and manifest format v3 for the new tour metadata while preserving v1 and v2 compatibility
+
 ## 0.8.16
 
 - Clarified authored-tour errors when a document requires a newer format version

package/cli/present.js

@@ -6,7 +6,7 @@ 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 } = require('./tourFile.js');
+const { loadTourSource, parseTourSourceText, buildManifestForTourSource } = require('./tourFile.js');
 const { createTourHistory } = require('./tourHistory.js');
 
 const MIME_TYPES = new Map([
@@ -21,15 +21,15 @@ const MIME_TYPES = new Map([
 
 async function startPresentation(args, cwd, packageRoot, options = {}) {
     const { headRef, baseRef, tourPath, explicitHeadRef } = parsePresentArgs(args);
-    const story = process.env.BYGONE_TOUR_STORY
+    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 builtManifest = buildChangeTourManifest(cwd, {
         headRef: explicitHeadRef || source?.range?.head || headRef,
         baseRef: baseRef || source?.range?.base,
-        title: process.env.BYGONE_TOUR_TITLE,
-        sourceUrl: process.env.BYGONE_TOUR_SOURCE_URL,
+        title: options.ignoreEnvironment ? undefined : process.env.BYGONE_TOUR_TITLE,
+        sourceUrl: options.ignoreEnvironment ? undefined : process.env.BYGONE_TOUR_SOURCE_URL,
         story,
         source
     });
@@ -38,7 +38,7 @@ async function startPresentation(args, cwd, packageRoot, options = {}) {
         : builtManifest;
     const history = createTourHistory(manifest);
     const serializedManifest = `${JSON.stringify(manifest, null, 2)}\n`;
-    const outputPath = process.env.BYGONE_TOUR_OUTPUT;
+    const outputPath = options.ignoreEnvironment ? undefined : process.env.BYGONE_TOUR_OUTPUT;
     if (outputPath) {
         const resolvedOutput = path.resolve(cwd, outputPath);
         mkdirSync(path.dirname(resolvedOutput), { recursive: true });
@@ -49,13 +49,46 @@ async function startPresentation(args, cwd, packageRoot, options = {}) {
     const tourWindowTitle = buildTourWindowTitle(manifest, 'Bygone');
     const presenterIndexPath = path.join(packageRoot, 'web', 'index.html');
     let presenterIndexTemplate;
+    // Uploaded documents remain immutable, scoped to this existing repository,
+    // and addressed independently so opening one cannot mutate another tab.
+    const uploadedTours = new Map();
 
     const server = createServer((request, response) => {
         const requestUrl = new URL(request.url || '/', 'http://127.0.0.1');
-        if (requestUrl.pathname === '/history/list' || requestUrl.pathname === '/history/diff') {
+        if (requestUrl.pathname === '/tour/open') {
             if (request.method !== 'POST') return respondJson(response, 405, { error: 'Method not allowed' });
             if (!isSameOriginLoopbackRequest(request)) return respondJson(response, 403, { error: 'Forbidden' });
-            if (!history) return respondJson(response, 404, { error: 'History requires a version 2 tour.' });
+            if (uploadedTours.size >= 16) return respondJson(response, 409, { error: 'This presentation has reached its open-document limit. Start a new presentation to open more documents.' });
+            let body = '';
+            request.setEncoding('utf8');
+            request.on('data', (chunk) => {
+                body += chunk;
+                if (Buffer.byteLength(body, 'utf8') > 2 * 1024 * 1024) { respondJson(response, 413, { error: 'Request too large' }); request.destroy(); }
+            });
+            request.on('end', () => {
+                if (response.writableEnded) return;
+                try {
+                    const uploadedSource = parseTourSourceText(JSON.parse(body).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 });
+                } 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 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);
+        const requestHistory = loadedTour ? loadedTour.history : history;
+        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') {
+            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.' });
             let body = '';
             request.setEncoding('utf8');
             request.on('data', chunk => {
@@ -69,7 +102,15 @@ async function startPresentation(args, cwd, packageRoot, options = {}) {
                 if (response.writableEnded) return;
                 try {
                     const input = JSON.parse(body);
-                    const result = requestUrl.pathname === '/history/list' ? history.list(input) : history.diff(input);
+                    const result = requestUrl.pathname === '/history/list'
+                        ? requestHistory.list(input)
+                        : requestUrl.pathname === '/history/diff'
+                            ? requestHistory.diff(input)
+                            : requestUrl.pathname === '/history/compare'
+                                ? requestHistory.compare(input)
+                                : requestUrl.pathname === '/history/compare-many'
+                                    ? requestHistory.compareMany(input)
+                                    : requestHistory.revisions(input);
                     respondJson(response, 200, result);
                 } catch {
                     respondJson(response, 400, { error: 'Could not load history for this file and revision.' });
@@ -125,7 +166,7 @@ async function startPresentation(args, cwd, packageRoot, options = {}) {
         });
         createReadStream(targetPath).on('error', () => respond(response, 500, 'Read failed')).pipe(response);
     });
-    const requestedPort = readPort(process.env.BYGONE_TOUR_PORT);
+    const requestedPort = readPort(options.ignoreEnvironment ? undefined : process.env.BYGONE_TOUR_PORT);
     await new Promise((resolve, reject) => {
         server.once('error', reject);
         server.listen(requestedPort, '127.0.0.1', resolve);

package/cli/tourFile.js

@@ -48,6 +48,14 @@ 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 });
+}
+
+function parseTourSourceText(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.');
+    }
     let documents;
     try {
         documents = loadYamlDocuments(text);
@@ -84,5 +92,6 @@ module.exports = {
     DEFAULT_MAX_TOUR_SOURCE_BYTES,
     buildManifestForTourSource,
     loadTourSource,
+    parseTourSourceText,
     readTourSourceDocument
 };

package/cli/tourHistory.js

@@ -1,10 +1,22 @@
 const { execFileSync } = require('child_process');
 const { realpathSync } = require('fs');
+const { TextDecoder } = require('util');
 const path = require('path');
 const { parseNameStatusZ } = require('../out/gitComparison.js');
 
-function git(root, args) {
-    return execFileSync('git', args, { cwd: root, encoding: 'utf8', maxBuffer: 8 * 1024 * 1024, stdio: ['ignore', 'pipe', 'pipe'] });
+const DEFAULT_HISTORY_MAX_FILE_BYTES = 2 * 1024 * 1024;
+const DEFAULT_HISTORY_MAX_LINE_BYTES = 64 * 1024;
+const DEFAULT_GIT_MAX_BUFFER_BYTES = 64 * 1024 * 1024;
+
+function git(root, args, options = {}) {
+    const encoding = options.encoding || 'utf8';
+    const output = execFileSync('git', args, {
+        cwd: root,
+        encoding,
+        maxBuffer: options.maxBuffer || DEFAULT_GIT_MAX_BUFFER_BYTES,
+        stdio: ['ignore', 'pipe', 'pipe']
+    });
+    return encoding === 'utf8' ? output.trimEnd() : output;
 }
 
 function validatePath(value) {
@@ -19,13 +31,276 @@ function validateCommit(root, value) {
     if (typeof value !== 'string' || !/^[a-f0-9]{40,64}$/i.test(value)) {
         throw new Error('History requires a full Git commit ID.');
     }
-    const resolved = git(root, ['rev-parse', '--verify', `${value}^{commit}`]).trim();
+    let resolved;
+    try {
+        resolved = git(root, ['rev-parse', '--verify', `${value}^{commit}`]).trim();
+    } catch {
+        throw new Error('History commit could not be resolved.');
+    }
     if (resolved !== value.toLowerCase()) throw new Error('History commit could not be resolved.');
     return resolved;
 }
 
+function requireInput(input) {
+    if (!input || typeof input !== 'object' || Array.isArray(input)) {
+        throw new Error('History requires a request object.');
+    }
+    return input;
+}
+
+function listCommitHistory(root, commit) {
+    const output = git(root, ['log', '--topo-order', '--format=%x1e%H%x00%P%x00%s%x00%cI%x00', commit, '--']);
+    const entries = [];
+    for (const record of output.split('\x1e').slice(1)) {
+        const fields = record.split('\0');
+        const [oid, parents, summary, timestamp] = fields;
+        if (!oid) continue;
+        entries.push({
+            commit: oid,
+            oid,
+            parentCommit: parents.split(' ')[0] || null,
+            parents: parents.split(' ').filter(Boolean),
+            shortCommit: oid.slice(0, 7),
+            summary,
+            timestamp
+        });
+    }
+    return entries;
+}
+
+function listChangedPaths(root, from, to) {
+    return parseNameStatusZ(git(root, [
+        '--literal-pathspecs',
+        'diff',
+        '--no-ext-diff',
+        '--no-textconv',
+        '--name-status',
+        '-z',
+        '--find-renames',
+        '--find-copies',
+        from,
+        to,
+        '--'
+    ]));
+}
+
+function pathPair(changedPath) {
+    const followsPath = (changedPath.kind === 'renamed' || changedPath.kind === 'copied')
+        && Boolean(changedPath.previousPath);
+    return {
+        leftPath: changedPath.kind === 'added'
+            ? null
+            : followsPath ? changedPath.previousPath : changedPath.path,
+        rightPath: changedPath.kind === 'deleted' ? null : changedPath.path
+    };
+}
+
+function parseNumstatValue(value) {
+    if (value === '-') return 0;
+    const parsed = Number.parseInt(value, 10);
+    return Number.isFinite(parsed) && parsed >= 0 ? parsed : 0;
+}
+
+function readNumstats(root, from, to) {
+    const fields = git(root, [
+        '--literal-pathspecs',
+        'diff',
+        '--no-ext-diff',
+        '--no-textconv',
+        '--numstat',
+        '-z',
+        '--find-renames',
+        '--find-copies',
+        from,
+        to,
+        '--'
+    ]).split('\0');
+    const stats = [];
+    for (let index = 0; index < fields.length;) {
+        const header = fields[index++];
+        if (!header) continue;
+        const match = /^(\d+|-)\t(\d+|-)\t(.*)$/.exec(header);
+        if (!match) continue;
+        const stat = {
+            additions: parseNumstatValue(match[1]),
+            deletions: parseNumstatValue(match[2])
+        };
+        if (match[3]) {
+            stat.path = match[3];
+        } else {
+            // With -z, rename and copy records put their two paths in the
+            // following NUL-delimited fields.
+            stat.previousPath = fields[index++] || undefined;
+            stat.path = fields[index++] || undefined;
+        }
+        if (stat.path) stats.push(stat);
+    }
+    return stats;
+}
+
+function buildStatsMap(stats) {
+    const byPath = new Map();
+    for (const stat of stats) {
+        byPath.set(stat.path, stat);
+        if (stat.previousPath) byPath.set(stat.previousPath, stat);
+    }
+    return byPath;
+}
+
+function hasLineLongerThan(content, maxLineBytes) {
+    let lineStart = 0;
+    for (let index = 0; index < content.length; index += 1) {
+        if (content[index] !== 10) continue;
+        if (index - lineStart > maxLineBytes) return true;
+        lineStart = index + 1;
+    }
+    return content.length - lineStart > maxLineBytes;
+}
+
+function readGitText(root, oid, relativePath) {
+    if (!oid || !relativePath) return { kind: 'text', content: '' };
+    let content;
+    try {
+        content = git(root, ['cat-file', 'blob', `${oid}:${relativePath}`], {
+            encoding: 'buffer',
+            maxBuffer: DEFAULT_HISTORY_MAX_FILE_BYTES + 1
+        });
+    } catch (error) {
+        if (error && (error.code === 'ENOBUFS' || /maxBuffer|buffer length/i.test(String(error.message)))) {
+            return { kind: 'omitted', reason: 'History file is too large to display.' };
+        }
+        return { kind: 'omitted', reason: 'History file could not be read.' };
+    }
+    if (content.length > DEFAULT_HISTORY_MAX_FILE_BYTES) {
+        return { kind: 'omitted', reason: 'History file is too large to display.' };
+    }
+    if (content.includes(0)) {
+        return { kind: 'omitted', reason: 'Binary history files cannot be displayed.' };
+    }
+    try {
+        // Validate UTF-8 before converting so arbitrary binary data that does
+        // not contain a NUL byte is still omitted instead of being replaced.
+        new TextDecoder('utf-8', { fatal: true }).decode(content);
+    } catch {
+        return { kind: 'omitted', reason: 'Binary history files cannot be displayed.' };
+    }
+    if (hasLineLongerThan(content, DEFAULT_HISTORY_MAX_LINE_BYTES)) {
+        return { kind: 'omitted', reason: 'History file contains an oversized line.' };
+    }
+    return { kind: 'text', content: content.toString('utf8') };
+}
+
+function buildComparisonFile(root, from, to, changedPath, statsByPath) {
+    const pair = pathPair(changedPath);
+    const left = readGitText(root, from, pair.leftPath);
+    const right = readGitText(root, to, pair.rightPath);
+    const stats = statsByPath.get(changedPath.path) ||
+        (changedPath.previousPath ? statsByPath.get(changedPath.previousPath) : undefined);
+    const additions = stats?.additions || 0;
+    const deletions = stats?.deletions || 0;
+    const leftLabel = pair.leftPath
+        ? `${pair.leftPath} @ ${from.slice(0, 7)}`
+        : `${changedPath.path} (absent)`;
+    const rightLabel = pair.rightPath
+        ? `${pair.rightPath} @ ${to.slice(0, 7)}`
+        : `${changedPath.path} (absent)`;
+    const reason = left.kind === 'omitted' ? left.reason : right.kind === 'omitted' ? right.reason : undefined;
+    const result = {
+        kind: reason ? 'omitted' : 'text-diff',
+        path: changedPath.path,
+        ...(changedPath.previousPath ? { previousPath: changedPath.previousPath } : {}),
+        changeKind: changedPath.kind,
+        leftPath: pair.leftPath,
+        rightPath: pair.rightPath,
+        leftContent: reason ? '' : left.content,
+        rightContent: reason ? '' : right.content,
+        leftLabel,
+        rightLabel,
+        additions,
+        deletions
+    };
+    if (reason) result.reason = reason;
+    return result;
+}
+
+function buildUnchangedPath(root, from, to, filePath) {
+    const left = readGitText(root, from, filePath);
+    const right = readGitText(root, to, filePath);
+    const reason = left.kind === 'omitted' ? left.reason : right.kind === 'omitted' ? right.reason : undefined;
+    const result = {
+        kind: reason ? 'omitted' : 'text-diff',
+        path: filePath,
+        changeKind: 'unchanged',
+        leftPath: filePath,
+        rightPath: filePath,
+        leftContent: reason ? '' : left.content,
+        rightContent: reason ? '' : right.content,
+        leftLabel: `${filePath} @ ${from.slice(0, 7)}`,
+        rightLabel: `${filePath} @ ${to.slice(0, 7)}`,
+        additions: 0,
+        deletions: 0
+    };
+    if (reason) result.reason = reason;
+    return result;
+}
+
+function pathExistsAt(root, oid, filePath) {
+    try {
+        return git(root, ['cat-file', '-e', `${oid}:${filePath}`]) === '';
+    } catch {
+        return false;
+    }
+}
+
+function aggregateComparisonFiles(commits, comparisons) {
+    const groups = [];
+    for (const [pairIndex, comparison] of comparisons.entries()) {
+        for (const file of comparison.files) {
+            const aliases = [file.path, file.previousPath, file.leftPath, file.rightPath].filter(Boolean);
+            const matches = groups.filter(group => aliases.some(alias => group.aliases.has(alias)));
+            const group = matches.shift() || { aliases: new Set(), files: [], panels: Array(commits.length).fill(null) };
+            if (!groups.includes(group)) groups.push(group);
+            for (const duplicate of matches) {
+                for (const alias of duplicate.aliases) group.aliases.add(alias);
+                group.files.push(...duplicate.files);
+                for (let index = 0; index < group.panels.length; index += 1) group.panels[index] ||= duplicate.panels[index];
+                groups.splice(groups.indexOf(duplicate), 1);
+            }
+            for (const alias of aliases) group.aliases.add(alias);
+            group.files.push(file);
+            if (file.kind === 'text-diff') {
+                group.panels[pairIndex] = { content: file.leftContent, path: file.leftPath || file.previousPath || file.path };
+                group.panels[pairIndex + 1] = { content: file.rightContent, path: file.rightPath || file.path };
+            }
+        }
+    }
+    return groups.map(group => {
+        for (let index = 1; index < group.panels.length; index += 1) group.panels[index] ||= group.panels[index - 1];
+        for (let index = group.panels.length - 2; index >= 0; index -= 1) group.panels[index] ||= group.panels[index + 1];
+        const source = group.files[group.files.length - 1];
+        const filePath = [...group.panels].reverse().find(panel => panel?.path)?.path || source.path;
+        const omitted = group.files.find(file => file.kind === 'omitted');
+        return {
+            kind: omitted ? 'omitted' : 'text-diff',
+            path: filePath,
+            changeKind: source.changeKind,
+            additions: group.files.reduce((sum, file) => sum + (file.additions || 0), 0),
+            deletions: group.files.reduce((sum, file) => sum + (file.deletions || 0), 0),
+            ...(omitted ? { reason: omitted.reason } : {}),
+            comparisonPanels: group.panels.map((panel, index) => ({
+                id: `compare-${commits[index]}`,
+                label: `${panel?.path || filePath} @ ${commits[index].slice(0, 7)}`,
+                commit: commits[index],
+                path: panel?.path || filePath,
+                content: panel?.content || '',
+                editable: false
+            }))
+        };
+    });
+}
+
 function createTourHistory(manifest) {
-    if (manifest.version !== 2) return null;
+    if (manifest.version < 2) return null;
     let root;
     try {
         root = realpathSync(manifest.repository.root);
@@ -35,13 +310,38 @@ function createTourHistory(manifest) {
     } catch {
         throw new Error('This v2 tour requires its originating Git repository. Restore the repository before presenting it.');
     }
+    function compare(input) {
+        input = requireInput(input);
+        const from = validateCommit(root, input.from);
+        const to = validateCommit(root, input.to);
+        const changedPaths = listChangedPaths(root, from, to);
+        const statsByPath = buildStatsMap(readNumstats(root, from, to));
+        if (input.path !== undefined) {
+            const filePath = validatePath(input.path);
+            const changedPath = changedPaths.find(item => item.path === filePath || item.previousPath === filePath);
+            if (changedPath) return { from, to, files: [buildComparisonFile(root, from, to, changedPath, statsByPath)] };
+            if (!pathExistsAt(root, from, filePath) && !pathExistsAt(root, to, filePath)) return { from, to, files: [] };
+            return { from, to, files: [buildUnchangedPath(root, from, to, filePath)] };
+        }
+        return { from, to, files: changedPaths.map(changedPath => buildComparisonFile(root, from, to, changedPath, statsByPath)) };
+    }
     return {
         list(input) {
+            input = requireInput(input);
+            if (input.path === undefined) {
+                const commit = validateCommit(root, input.commit || manifest.range.headOid);
+                const entries = listCommitHistory(root, commit);
+                return {
+                    entries,
+                    selectedIndex: entries.length ? 0 : -1,
+                    selectedCommit: entries[0]?.commit || null
+                };
+            }
             const filePath = validatePath(input.path);
             const commit = validateCommit(root, input.commit || manifest.range.headOid);
             // Follow the file backwards from the requested revision, including deleted
             // files and rename records; no working-tree file needs to exist.
-            const output = git(root, ['--literal-pathspecs', 'log', '--follow', '-M', '--max-count=250',
+            const output = git(root, ['--literal-pathspecs', 'log', '--topo-order', '--follow', '-M',
                 '--format=%x1e%H%x00%P%x00%s%x00%cI%x00', '--name-status', '-z', commit, '--', filePath]);
             const entries = [];
             let historicalPath = filePath;
@@ -61,21 +361,47 @@ function createTourHistory(manifest) {
                     ? 'Showing the closest preceding commit that changed this file.'
                     : 'No file history exists at this revision.' } : {}) };
         },
+        revisions(input) {
+            input = requireInput(input);
+            const commit = validateCommit(root, input.commit || manifest.range.headOid);
+            const entries = listCommitHistory(root, commit);
+            return {
+                revisions: entries,
+                entries,
+                selectedIndex: entries.length ? 0 : -1,
+                selectedCommit: entries[0]?.commit || null
+            };
+        },
         diff(input) {
-            const filePath = validatePath(input.path);
+            input = requireInput(input);
+            let filePath = validatePath(input.path);
             const commit = validateCommit(root, input.commit);
+            // Resolve the file's historical name without changing the commit axis.
+            // Only cross a rename when this revision is an ancestor of that rename.
+            if (input.head && !pathExistsAt(root, commit, filePath)) {
+                const head = validateCommit(root, input.head);
+                const lineage = this.list({ path: filePath, commit: head }).entries;
+                for (const entry of lineage) {
+                    if (!entry.previousPath) continue;
+                    try {
+                        git(root, ['merge-base', '--is-ancestor', commit, entry.parentCommit]);
+                        filePath = entry.previousPath;
+                    } catch { /* This rename is not ahead of the requested revision. */ }
+                    if (pathExistsAt(root, commit, filePath)) break;
+                }
+            }
             const parents = git(root, ['show', '-s', '--format=%P', commit]).trim();
             const parentCommit = parents.split(' ')[0] || null;
-            const changes = parseNameStatusZ(git(root, ['diff-tree', '--root', '--no-commit-id', '-r', '-M', '--name-status', '-z',
-                ...(parentCommit ? [parentCommit, commit] : [commit])]));
+            const changes = parseNameStatusZ(git(root, ['--literal-pathspecs', 'diff-tree', '--root', '--no-commit-id', '-r', '-M', '--name-status', '-z',
+                ...(parentCommit ? [parentCommit, commit] : [commit]), '--']));
             const change = changes.find(item => item.path === filePath || item.previousPath === filePath);
             const rightPath = change?.path || filePath;
             const leftPath = change?.previousPath || filePath;
             function read(oid, name, absent) {
-                if (!oid || absent) return '';
-                const content = git(root, ['show', `${oid}:${name}`]);
-                if (content.includes('\0') || content.length > 2 * 1024 * 1024) throw new Error('History file is binary or too large to display.');
-                return content;
+                if (!oid || absent || !pathExistsAt(root, oid, name)) return '';
+                const content = readGitText(root, oid, name);
+                if (content.kind === 'omitted') throw new Error(content.reason);
+                return content.content;
             }
             return { commit, parentCommit, path: rightPath,
                 ...(change?.previousPath ? { previousPath: change.previousPath } : {}),
@@ -83,6 +409,22 @@ function createTourHistory(manifest) {
                 rightContent: read(commit, rightPath, change?.kind === 'deleted'),
                 leftLabel: `${leftPath} @ ${parentCommit ? parentCommit.slice(0, 7) : 'empty'}`,
                 rightLabel: `${rightPath} @ ${commit.slice(0, 7)}` };
+        },
+        compare,
+        compareMany(input) {
+            input = requireInput(input);
+            if (!Array.isArray(input.commits) || input.commits.length < 2) throw new Error('Comparison requires at least two commits.');
+            const commits = input.commits.map(commit => validateCommit(root, commit));
+            if (new Set(commits).size !== commits.length) throw new Error('Comparison commits must be unique.');
+            const comparisons = commits.slice(0, -1).map((from, index) => compare({
+                from,
+                to: commits[index + 1],
+                ...(input.path !== undefined ? { path: input.path } : {})
+            }));
+            return {
+                commits,
+                files: aggregateComparisonFiles(commits, comparisons)
+            };
         }
     };
 }