@davmash/bygone 0.7.1 → 0.8.3

package/out/tourCoverage.js

@@ -1292,7 +1292,11 @@ function applySource(source, defaultScenes, repoRoot) {
         continue;
       }
       if (authoredScene.kind === "stacked-diff") {
-        const stackedScene = buildStackedScene(repoRoot, authoredScene);
+        const stackedScene = buildStackedScene(
+          repoRoot,
+          authoredScene,
+          [...available.keys()]
+        );
         scenes.push(stackedScene);
         sceneIds.push(stackedScene.id);
         continue;
@@ -1400,8 +1404,7 @@ function buildDeconstructedManifestScene(repoRoot, source, baseRef, targetRef) {
     }))
   };
 }
-function buildStackedScene(repoRoot, source) {
-  var _a;
+function buildStackedScene(repoRoot, source, availableFilePaths) {
   const stack = source.stack.map((entry) => ({
     id: entry.id,
     ref: entry.ref,
@@ -1421,15 +1424,18 @@ function buildStackedScene(repoRoot, source) {
     maxBuffer: 16 * 1024 * 1024,
     stdio: ["ignore", "pipe", "pipe"]
   })));
-  const renamedPreviousPaths = new Set(adjacentChanges.flatMap((changes) => changes.map((change) => change.previousPath).filter((candidate) => Boolean(candidate))));
-  const changedFiles = [...new Set(adjacentChanges.flatMap((changes) => changes.map((change) => change.path)))].filter((filePath) => !renamedPreviousPaths.has(filePath)).sort();
-  const filePaths = ((_a = source.files) == null ? void 0 : _a.length) ? [...new Set(source.files)] : changedFiles;
-  for (const step of source.steps) {
-    if (!filePaths.includes(step.file)) throw new Error(`Stacked step ${step.id} references undeclared file ${step.file}.`);
-  }
+  const filePaths = [.../* @__PURE__ */ new Set([
+    ...availableFilePaths,
+    ...source.files || [],
+    ...source.steps.map((step) => step.file)
+  ])].sort();
   if (filePaths.length === 0) throw new Error(`Stacked scene ${source.id} has no changed files.`);
+  const requiredFilePaths = /* @__PURE__ */ new Set([
+    ...source.files || [],
+    ...source.steps.map((step) => step.file)
+  ]);
   let totalContentBytes = 0;
-  const files = filePaths.map((filePath) => {
+  const files = filePaths.flatMap((filePath) => {
     const aliases = /* @__PURE__ */ new Set([filePath]);
     for (const changes of adjacentChanges) {
       for (const change of changes) {
@@ -1439,26 +1445,35 @@ function buildStackedScene(repoRoot, source) {
         }
       }
     }
-    const panels = stack.map((entry) => {
+    let fileContentBytes = 0;
+    const panels = [];
+    for (const entry of stack) {
       const resolvedPath = [...aliases].find((candidate) => gitBlobExists(repoRoot, entry.oid, candidate));
       if (!resolvedPath) {
-        return { id: entry.id, label: `${entry.label} / ${filePath} (missing)`, content: "", exists: false };
+        panels.push({ id: entry.id, label: `${entry.label} / ${filePath} (missing)`, content: "", exists: false });
+        continue;
       }
       const content = readGitText(repoRoot, entry.oid, resolvedPath, DEFAULT_MAX_TOUR_FILE_BYTES, DEFAULT_MAX_TOUR_LINE_BYTES);
-      if (content.kind !== "text") throw new Error(`Stacked tour file is binary or too large: ${resolvedPath}`);
-      totalContentBytes += Buffer.byteLength(content.content);
-      if (totalContentBytes > DEFAULT_MAX_STACK_CONTENT_BYTES) {
-        throw new Error(`Stacked tour content exceeds ${DEFAULT_MAX_STACK_CONTENT_BYTES} bytes.`);
+      if (content.kind !== "text") {
+        if (requiredFilePaths.has(filePath)) {
+          throw new Error(`Stacked tour file is binary or too large: ${resolvedPath}`);
+        }
+        return [];
       }
-      return {
+      fileContentBytes += Buffer.byteLength(content.content);
+      panels.push({
         id: entry.id,
         label: `${entry.label} / ${resolvedPath}`,
         path: resolvedPath,
         content: content.content,
         exists: true
-      };
-    });
-    return { path: filePath, panels };
+      });
+    }
+    totalContentBytes += fileContentBytes;
+    if (totalContentBytes > DEFAULT_MAX_STACK_CONTENT_BYTES) {
+      throw new Error(`Stacked tour content exceeds ${DEFAULT_MAX_STACK_CONTENT_BYTES} bytes.`);
+    }
+    return [{ path: filePath, panels }];
   });
   const stackIds = stack.map((entry) => entry.id);
   return {
@@ -1472,7 +1487,7 @@ function buildStackedScene(repoRoot, source) {
     stack,
     files,
     steps: source.steps.map((step) => {
-      var _a2, _b;
+      var _a, _b;
       return {
         id: step.id,
         title: step.title,
@@ -1480,7 +1495,7 @@ function buildStackedScene(repoRoot, source) {
         file: step.file,
         pairIndex: stackIds.indexOf(step.pair[0]),
         side: step.side || "right",
-        startLine: (_a2 = step.lines) == null ? void 0 : _a2[0],
+        startLine: (_a = step.lines) == null ? void 0 : _a[0],
         endLine: (_b = step.lines) == null ? void 0 : _b[1]
       };
     })

package/package.json

@@ -1,19 +1,19 @@
 {
   "name": "@davmash/bygone",
-  "version": "0.7.1",
+  "version": "0.8.3",
   "description": "See how change happened. Visual diff and file history.",
   "author": "David Mashburn",
   "license": "MIT",
   "homepage": "https://github.com/davidmashburn/bygone",
   "repository": {
     "type": "git",
-    "url": "https://github.com/davidmashburn/bygone.git"
+    "url": "git+https://github.com/davidmashburn/bygone.git"
   },
   "bugs": {
     "url": "https://github.com/davidmashburn/bygone/issues"
   },
   "bin": {
-    "bygone": "./bin/bygone.js"
+    "bygone": "bin/bygone.js"
   },
   "main": "./out/standalone-main.js",
   "files": [
@@ -27,6 +27,7 @@
     "docs/",
     "examples/",
     "schemas/",
+    "skills/",
     "README.md",
     "LICENSE.txt",
     "CHANGELOG.md"

package/skills/pr-tour-guide/SKILL.md

@@ -0,0 +1,238 @@
+---
+name: pr-tour-guide
+description: Act as a PR Tour Guide by generating, validating, compiling, and presenting evidence-grounded Bygone code-change tours from Git ranges. Use for requests such as "Tour this commit for me," or whenever an AI coding agent should explain a pull request, branch, commit, or code change as a guided walkthrough; create or repair a .bygone file; produce an LLM-ready Bygone change context; connect narrative claims to exact source evidence; or turn a diff into a browser-presentable review or demo. Always print the exact `bygone` CLI command to open the resulting diff, review, tour, or history view.
+---
+
+# PR Tour Guide
+
+Use Bygone as the deterministic evidence and rendering layer. Treat the language model as the narrative planner, never as the authority on Git ranges or source locations.
+
+## Install this skill
+
+For Cursor, Codex, Claude Code, and other agents supported by the skills CLI:
+
+```sh
+npx skills add davidmashburn/bygone -s pr-tour-guide -g -y
+```
+
+List without installing:
+
+```sh
+npx skills add davidmashburn/bygone --list
+```
+
+From a Bygone source checkout, install the local copy instead:
+
+```sh
+npx skills add ./skills/pr-tour-guide -g -y
+```
+
+## Install Bygone
+
+This skill requires the `bygone` CLI with `tour context`, `tour schema`, `tour validate`, and `tour compile`. Install only when the user asks or when the task cannot proceed without it.
+
+**macOS (desktop app + CLI, recommended):**
+
+```sh
+brew tap davidmashburn/bygone
+brew install --cask bygone-desktop
+```
+
+First install may require `brew trust davidmashburn/bygone`.
+
+**CLI only (Node.js required):**
+
+```sh
+npm install -g @davmash/bygone
+```
+
+**macOS without Homebrew:** download the DMG from [GitHub Releases](https://github.com/davidmashburn/bygone/releases), then choose **Help → Install Command Line Tools…** in the app.
+
+**From a Bygone source checkout:**
+
+```sh
+npm install
+npm run dev:sync
+```
+
+## Locate and verify Bygone
+
+Run `bygone --help`. In a Bygone source checkout whose installed command is stale, use `node ./bin/bygone.js` instead.
+
+Verify tour support before authoring:
+
+```sh
+bygone tour schema >/dev/null
+```
+
+If neither `bygone` nor `node ./bin/bygone.js` exposes the `tour` subcommands, stop, share the install commands above, and report that the toolchain is unavailable rather than guessing.
+
+Do not rebuild, commit, push, publish, or open a browser unless the user requests it or the surrounding task clearly requires it.
+
+## Build the evidence context
+
+Determine the intended head and base from the request and repository state. Prefer an explicit base; do not guess when different bases would materially change the explanation.
+
+For a hosted review, resolve both immutable endpoint OIDs from provider metadata. Never assume the current checkout is the requested review head. For GitHub:
+
+```sh
+PR_JSON="$(gh pr view <n> --json baseRefOid,headRefOid)"
+BASE_OID="$(jq -r .baseRefOid <<<"$PR_JSON")"
+HEAD_OID="$(jq -r .headRefOid <<<"$PR_JSON")"
+test -n "$BASE_OID" && test "$BASE_OID" != null
+test -n "$HEAD_OID" && test "$HEAD_OID" != null
+bygone tour context "$HEAD_OID" --base "$BASE_OID" --output /tmp/change-context.json
+```
+
+Use the equivalent API or CLI fields for other providers. If you are not reviewing a hosted change, compute the merge-base against the intended integration branch and pass that exact base OID or ref. Keep the existing preference for explicit endpoints and do not guess.
+
+Use immutable commit IDs in the eventual tour. Dirty working-tree changes are reported but excluded from committed-range context.
+
+Inspect progressively instead of loading every patch immediately:
+
+```sh
+jq '{range,summary,commits,files:[.files[]|{path,previousPath,changeKind,role,additions,deletions,binary,patchOmittedReason,symbolHints}]}' /tmp/change-context.json
+```
+
+Then read patches only for likely narrative-bearing files. Account explicitly for every `patchOmittedReason`; never claim to understand omitted binary or oversized evidence.
+
+Compiled tours and context dossiers are large because they embed source snapshots. Inspect them progressively and do not load every patch unless the narrative really needs it.
+
+## Plan the explanation
+
+Identify the smallest set of reviewer questions that makes the change understandable. Organize by conceptual dependency rather than filename order. Usually move through:
+
+1. motivation, contract, or invariant;
+2. core implementation;
+3. integration or side effects;
+4. failure behavior and proof.
+
+Keep secondary, generated, dependency, and mechanical files in Bygone's complete Files rail unless they alter a reviewer conclusion.
+
+Let the change determine the hierarchy. A chapter is a named conceptual arc containing one or more related scenes; a scene answers one reviewer question or advances one thesis. Do not target a fixed chapter count, and do not create a chapter merely to wrap each scene. Repeated one-scene chapters usually indicate that headings are being generated from a template instead of the change's actual structure.
+
+Scale the structure proportionally:
+
+- A small commit may need one chapter and one scene.
+- A normal pull request often needs one to three chapters with one or more scenes in each.
+- A broad release or long-lived branch may need several chapters, but each boundary must mark a real conceptual transition.
+- Prefer merging adjacent chapters when their scenes form one argument; split a chapter only when its scenes answer materially different reviewer questions.
+
+These are pacing heuristics, not quotas. Preserve asymmetry when one capability deserves substantially more explanation than another.
+
+Use these narrative constraints:
+
+- State one reviewer question or thesis per scene.
+- Give every chapter a coherent multi-scene arc when the material supports one; allow a single-scene chapter only when that scene is independently substantial.
+- Decompose scenes by conceptual need, not a fixed template; do not force every scene to use the same step count.
+- Prefer three to seven steps per scene.
+- Explain why focused code matters instead of paraphrasing syntax.
+- Keep summaries, bullets, annotations, and takeaways distinct; bullets that merely restate the summary are a defect.
+- Avoid intent, safety, performance, or runtime claims unsupported by the evidence.
+- Do not imply that the authored tour exhaustively reviews every changed file.
+
+## Author the source
+
+Retrieve the current contract:
+
+```sh
+bygone tour schema > /tmp/change-tour-source.schema.json
+```
+
+Write a `.bygone` file. The legacy `.bygone.yaml` spelling remains valid when
+generic YAML tooling requires it. Treat either authored source as Git-backed,
+not portable: pin `range.base` and `range.head` to the exact OIDs from the
+context, and keep the file within the corresponding repository so Bygone can
+resolve those objects. Use a compiled `.tour.json` only when a portable
+snapshot is required.
+
+For every step:
+
+- make one concise explanatory claim;
+- focus an anchor in `base` or `head` evidence;
+- prefer changed lines, using unchanged context only when it establishes a required boundary;
+- use the shortest snippet that is unique within that file and revision;
+- connect behavior to tests, error handling, or other concrete proof;
+- add a connection only when the relationship between two locations materially improves understanding.
+
+Never emit generated line numbers or hunk indexes. Verify candidate snippets against the pinned object when uncertain:
+
+```sh
+git show HEAD_OID:path/to/file | rg -F -n 'exact snippet'
+```
+
+Use `occurrence` only when repetition is intentional and stable. Treat rename identity as evidence rather than describing a rename as unrelated deletion and addition.
+
+## Validate and repair
+
+Always run validation before presenting or handing off:
+
+```sh
+bygone tour validate review.bygone --json
+```
+
+Repair every error. Do not weaken, delete, or redirect an anchor merely to make validation pass. If evidence no longer exists, revise the claim or report the broken premise.
+
+After structural validation, check that:
+
+Treat this as a required self-audit, not a claim the validator can prove. For each item, cite concrete evidence you actually opened or mark it not applicable; the hand-off must distinguish verified findings from interpretation.
+
+- the first step establishes enough context for later steps;
+- chapter boundaries follow conceptual transitions rather than a fixed count or one-scene-per-chapter pattern;
+- important production behavior is not hidden in the complete Files rail;
+- tests are connected to the behavior they prove;
+- connections express causal, contractual, data-flow, ordering, or proof relationships;
+- binary files and omitted patches are surfaced explicitly;
+- the final step supplies proof or a clear reviewer conclusion.
+
+## Always print the open command
+
+Whenever you create, validate, compile, recommend, or open a diff, review, tour, history view, or Git comparison, **always** print the exact one-line `bygone` command the user can paste to open it in the desktop app.
+
+Do this even when you also run the command yourself, when presentation was not requested, and when handing off artifacts. Use the real paths and refs from the work; prefer absolute paths when a tour or file lives outside the current directory.
+
+| Goal | Command template |
+| --- | --- |
+| Authored tour | `bygone -C <repository> present --tour <path/to/review.bygone>` |
+| Branch review (change set) | `bygone review <head> --base <base>` |
+| App-hosted range tour (no authored file) | `bygone present <head> --base <base>` |
+| Two-way file or directory compare | `bygone <left> <right>` |
+| Explicit diff mode | `bygone --diff <left> <right>` |
+| Multi-panel compare | `bygone <path1> <path2> <path3> [...]` |
+| Git refs compare | `bygone --git-diff <ref1> <ref2> [<ref3>...]` |
+| File or directory history | `bygone --history <path>` |
+| Repo directory history | `bygone` (from inside the Git repo) |
+
+Tour tooling that does not open the app (`tour context`, `tour validate`, `tour compile`, `tour coverage`) still warrants the matching open command when a human should inspect the result visually.
+
+## Compile or present
+
+Compile a portable manifest when the user needs an artifact:
+
+```sh
+bygone tour compile review.bygone --output review.tour.json
+```
+
+Open the interactive browser only when requested or useful for verifying the result:
+
+```sh
+bygone -C /absolute/path/to/repository present --tour review.bygone
+```
+
+Always print that same command with the real repository and tour paths, even if you do not run it. `-C` gives Bygone an explicit working directory without changing the user's shell directory.
+
+Compiled manifests contain source snapshots. Do not publish or upload them without explicit authorization.
+
+## Hand off
+
+Report:
+
+- the exact base and head OIDs;
+- the **open command** for the primary artifact (`bygone present --tour …`, `bygone review …`, `bygone --git-diff …`, etc.);
+- the source and compiled artifact paths;
+- authored chapter, scene, and step counts, plus compiled counts when the generated complete-change appendix changes them;
+- omitted or unread evidence;
+- validation and visual verification performed;
+- whether generated files are temporary, uncommitted, committed, or pushed.
+
+Distinguish syntactic grounding from interpretive correctness: Bygone proves that cited evidence exists at the pinned revision, not that the narrative's interpretation is unquestionably correct.

package/standalone/index.html

@@ -30,13 +30,13 @@
             <div id="change-toolbar" class="change-toolbar header-align-diff" hidden>
                 <div class="change-toolbar-main">
                     <div class="change-toolbar-nav">
-                        <button id="previous-file" class="change-button icon-button" type="button" title="Previous file" aria-label="Previous file">
+                        <button id="previous-file" class="change-button icon-button" type="button" title="Open previous file" aria-label="Previous file">
                             <svg viewBox="0 0 24 24" aria-hidden="true">
                                 <path d="M17 11l-5-5-5 5"></path>
                                 <path d="M17 18l-5-5-5 5" opacity="0.7"></path>
                             </svg>
                         </button>
-                        <button id="next-file" class="change-button change-button-primary icon-button" type="button" title="Next file" aria-label="Next file">
+                        <button id="next-file" class="change-button change-button-primary icon-button" type="button" title="Open next file" aria-label="Next file">
                             <svg viewBox="0 0 24 24" aria-hidden="true">
                                 <path d="M7 13l5 5 5-5"></path>
                                 <path d="M7 6l5 5 5-5" opacity="0.7"></path>
@@ -44,7 +44,7 @@
                         </button>
                     </div>
                     <div class="change-toolbar-center">
-                    <button id="previous-change" class="change-button icon-button" type="button" title="Previous difference (Cmd/Ctrl+Alt+Up)" aria-label="Previous difference">
+                    <button id="previous-change" class="change-button icon-button" type="button" title="Previous difference (Shift+F7 or Cmd/Ctrl+Shift+Up)" aria-label="Previous difference">
                         <svg viewBox="0 0 24 24" aria-hidden="true">
                             <path d="M12 19V5"></path>
                             <path d="M6 11l6-6 6 6"></path>
@@ -65,7 +65,7 @@
                             <path d="M5 5v14"></path>
                         </svg>
                     </button>
-                    <button id="next-change" class="change-button change-button-primary icon-button" type="button" title="Next difference (Cmd/Ctrl+Alt+Down)" aria-label="Next difference">
+                    <button id="next-change" class="change-button change-button-primary icon-button" type="button" title="Next difference (F7 or Cmd/Ctrl+Shift+Down)" aria-label="Next difference">
                         <svg viewBox="0 0 24 24" aria-hidden="true">
                             <path d="M12 5v14"></path>
                             <path d="M6 13l6 6 6-6"></path>
@@ -86,7 +86,7 @@
                         </svg>
                     </button>
                 </div>
-                <div class="change-hint">Cmd/Ctrl+Alt+Up/Down to jump.</div>
+                <div class="change-hint">F7 / Shift+F7 · Cmd/Ctrl+Shift+Up/Down to jump.</div>
             </div>
             <div id="history-toolbar" class="history-toolbar header-align-diff" hidden>
                 <div class="history-side history-side-left">
@@ -94,14 +94,14 @@
                     <div id="history-left-time" class="history-time"></div>
                 </div>
                 <div class="history-nav">
-                    <button id="history-back" class="history-button icon-button" type="button" title="Older commit" aria-label="Older commit">
+                    <button id="history-back" class="history-button icon-button" type="button" title="Open older commit (Alt+Left)" aria-label="Older commit">
                         <svg viewBox="0 0 24 24" aria-hidden="true">
                             <path d="M15 18l-6-6 6-6"></path>
                             <path d="M10 18l-6-6 6-6" opacity="0.7"></path>
                         </svg>
                     </button>
                     <div id="history-position" class="history-position" role="status" aria-live="polite" aria-atomic="true"></div>
-                    <button id="history-forward" class="history-button icon-button" type="button" title="Newer commit" aria-label="Newer commit">
+                    <button id="history-forward" class="history-button icon-button" type="button" title="Open newer commit (Alt+Right)" aria-label="Newer commit">
                         <svg viewBox="0 0 24 24" aria-hidden="true">
                             <path d="M9 18l6-6-6-6"></path>
                             <path d="M14 18l6-6-6-6" opacity="0.7"></path>

package/web/index.html

@@ -18,6 +18,18 @@
                 <div id="tour-stats" class="tour-stats"></div>
             </div>
         </header>
+        <section class="tour-search" aria-label="Search tour">
+            <div class="tour-search-controls">
+                <input id="tour-search-input" type="search" placeholder="Search tour" aria-label="Search tour narrative and code">
+                <select id="tour-search-scope" aria-label="Tour search scope" title="Tour search scope">
+                    <option value="all">Narrative + code</option>
+                    <option value="narrative">Narrative</option>
+                    <option value="code">Code</option>
+                </select>
+            </div>
+            <div id="tour-search-status" class="tour-search-status" role="status" aria-live="polite"></div>
+            <div id="tour-search-results" class="tour-search-results" role="listbox"></div>
+        </section>
         <div class="tour-rail-sections">
             <section class="tour-rail-section">
                 <header class="tour-rail-heading">
@@ -39,7 +51,7 @@
             <summary id="tour-commits-summary">0 commits</summary>
             <ol id="tour-commits" class="tour-commits"></ol>
         </details>
-        <div id="tour-sidebar-resizer" class="tour-sidebar-resizer" role="separator" aria-label="Resize tour sidebar" aria-orientation="vertical" aria-valuemin="240" aria-valuemax="600" tabindex="0"></div>
+        <div id="tour-sidebar-resizer" class="tour-sidebar-resizer" role="separator" aria-label="Resize tour sidebar" title="Resize tour sidebar (Left/Right; Home/End)" aria-orientation="vertical" aria-valuemin="240" aria-valuemax="600" tabindex="0"></div>
     </aside>
     <button id="tour-sidebar-show" class="tour-sidebar-show" type="button" title="Show tour sidebar" aria-label="Show tour sidebar" hidden>›</button>
     <section id="tour-narrative" class="tour-narrative" hidden>
@@ -66,6 +78,7 @@
             </div>
         </div>
     </section>
+    <div id="tour-narrative-resizer" class="tour-narrative-resizer" role="separator" aria-label="Resize tour header" title="Resize tour header (Up/Down; Home/End)" aria-orientation="horizontal" aria-valuemin="180" tabindex="0"></div>
     <div class="web-toolbar">
         <div class="web-toolbar-group">
             <button id="web-compare-test" type="button" title="Compare sample files">Compare Test Files</button>
@@ -100,13 +113,13 @@
             <div id="change-toolbar" class="change-toolbar header-align-diff" hidden>
                 <div class="change-toolbar-main">
                     <div class="change-toolbar-nav">
-                        <button id="previous-file" class="change-button icon-button" type="button" title="Previous file" aria-label="Previous file">
+                        <button id="previous-file" class="change-button icon-button" type="button" title="Open previous file" aria-label="Previous file">
                             <svg viewBox="0 0 24 24" aria-hidden="true">
                                 <path d="M17 11l-5-5-5 5"></path>
                                 <path d="M17 18l-5-5-5 5"></path>
                             </svg>
                         </button>
-                        <button id="next-file" class="change-button icon-button" type="button" title="Next file" aria-label="Next file">
+                        <button id="next-file" class="change-button icon-button" type="button" title="Open next file" aria-label="Next file">
                             <svg viewBox="0 0 24 24" aria-hidden="true">
                                 <path d="M7 13l5 5 5-5"></path>
                                 <path d="M7 6l5 5 5-5"></path>
@@ -114,7 +127,7 @@
                         </button>
                     </div>
                     <div class="change-toolbar-center">
-                        <button id="previous-change" class="change-button icon-button" type="button" title="Previous difference (Cmd/Ctrl+Alt+Up)" aria-label="Previous difference">
+                        <button id="previous-change" class="change-button icon-button" type="button" title="Previous difference (Shift+F7 or Cmd/Ctrl+Shift+Up)" aria-label="Previous difference">
                             <svg viewBox="0 0 24 24" aria-hidden="true">
                                 <path d="M12 19V5"></path>
                                 <path d="M6 11l6-6 6 6"></path>
@@ -135,7 +148,7 @@
                                 <path d="M5 5v14"></path>
                             </svg>
                         </button>
-                        <button id="next-change" class="change-button change-button-primary icon-button" type="button" title="Next difference (Cmd/Ctrl+Alt+Down)" aria-label="Next difference">
+                        <button id="next-change" class="change-button change-button-primary icon-button" type="button" title="Next difference (F7 or Cmd/Ctrl+Shift+Down)" aria-label="Next difference">
                             <svg viewBox="0 0 24 24" aria-hidden="true">
                                 <path d="M12 5v14"></path>
                                 <path d="M6 13l6 6 6-6"></path>
@@ -156,7 +169,7 @@
                         </svg>
                     </button>
                 </div>
-                <div class="change-hint">Cmd/Ctrl+Alt+Up/Down to jump.</div>
+                <div class="change-hint">F7 / Shift+F7 · Cmd/Ctrl+Shift+Up/Down to jump.</div>
             </div>
             <div id="history-toolbar" class="history-toolbar header-align-diff" hidden>
                 <div class="history-side history-side-left">
@@ -164,14 +177,14 @@
                     <div id="history-left-time" class="history-time"></div>
                 </div>
                 <div class="history-nav">
-                    <button id="history-back" class="history-button icon-button" type="button" title="Older commit" aria-label="Older commit">
+                    <button id="history-back" class="history-button icon-button" type="button" title="Open older commit" aria-label="Older commit">
                         <svg viewBox="0 0 24 24" aria-hidden="true">
                             <path d="M15 18l-6-6 6-6"></path>
                             <path d="M10 18l-6-6 6-6" opacity="0.7"></path>
                         </svg>
                     </button>
                     <div id="history-position" class="history-position" role="status" aria-live="polite" aria-atomic="true"></div>
-                    <button id="history-forward" class="history-button icon-button" type="button" title="Newer commit" aria-label="Newer commit">
+                    <button id="history-forward" class="history-button icon-button" type="button" title="Open newer commit" aria-label="Newer commit">
                         <svg viewBox="0 0 24 24" aria-hidden="true">
                             <path d="M9 18l6-6-6-6"></path>
                             <path d="M14 18l6-6-6-6" opacity="0.7"></path>