mergie-cli 0.1.0

package/src/web/lib/commentFilters.ts

@@ -0,0 +1,36 @@
+import type { AllCommentEntry } from "@/daemon/allComments.ts";
+
+/** Author filter: everyone, only mine, or only other people's. */
+export type AuthorFilter = "all" | "mine" | "others";
+
+/**
+ * Source filter for the All-comments view. A comment posted from mergie is a
+ * GitHub comment, so it falls under `github` (never `local`); `local` is only
+ * never-posted drafts.
+ */
+export type SourceFilter = "all" | "local" | "github";
+
+/** The active filters on the All-comments view. */
+export interface CommentFilters {
+  /** Filter by authorship. */
+  author: AuthorFilter;
+  /** Filter by origin. */
+  source: SourceFilter;
+  /** File path to restrict to; empty string means all files. */
+  file: string;
+}
+
+/**
+ * Filter unified comment entries by author, source, and file. Pure — returns a
+ * new array and never mutates its input.
+ */
+export function filterAllComments(entries: AllCommentEntry[], filters: CommentFilters): AllCommentEntry[] {
+  return entries.filter((e) => {
+    if (filters.author === "mine" && !e.mine) return false;
+    if (filters.author === "others" && e.mine) return false;
+    if (filters.source === "local" && e.origin !== "local") return false;
+    if (filters.source === "github" && e.origin === "local") return false;
+    if (filters.file !== "" && e.path !== filters.file) return false;
+    return true;
+  });
+}

package/src/web/lib/commentVisibility.ts

@@ -0,0 +1,90 @@
+import type { AllCommentEntry } from "@/daemon/allComments.ts";
+import type { FileView } from "@/daemon/reviewService.ts";
+
+/** DOM id for a rendered local (mergie) comment element. */
+export function localCommentDomId(localId: number): string {
+  return `comment-local-${localId}`;
+}
+
+/** DOM id for a rendered synced GitHub thread element. */
+export function githubCommentDomId(githubId: string): string {
+  return `comment-gh-${githubId}`;
+}
+
+/**
+ * Ordered element ids to try scrolling to for an entry. A GitHub-backed comment
+ * usually renders as its synced thread (`comment-gh-…`), but a just-posted one
+ * that has not been fetched back yet still renders as a local element
+ * (`comment-local-…`) — so posted entries list both, thread first.
+ */
+export function commentDomIdCandidates(entry: AllCommentEntry): string[] {
+  const ids: string[] = [];
+  if (entry.githubId !== null) ids.push(githubCommentDomId(entry.githubId));
+  if (entry.localId !== null) ids.push(localCommentDomId(entry.localId));
+  return ids;
+}
+
+/**
+ * Whether an All-comments entry is actually rendered in the current diff range.
+ *
+ * A comment is "visible in the diff" only when the range view has anchored it to
+ * a hunk — the same strict anchoring the diff uses (exact line/hunk present).
+ * Local drafts and mergie-posted comments match by their local comment id;
+ * GitHub-origin comments (and the posted comment's synced thread) match by the
+ * thread's root GitHub id. If it matches nothing rendered, honoring a click on
+ * it would require changing the range, so it is treated as out-of-range.
+ *
+ * Pure — reads only its arguments, mutates nothing.
+ *
+ * @param entry The unified comment entry the user clicked.
+ * @param files The files/hunks currently rendered for the selected range.
+ */
+export function commentVisibleInDiff(entry: AllCommentEntry, files: FileView[]): boolean {
+  return commentHunkHash(entry, files) !== null;
+}
+
+/**
+ * The content hash of the hunk that anchors this comment within `files`, or
+ * `null` if the comment is not anchored anywhere in them. Same matching as
+ * {@link commentVisibleInDiff} (local id or synced-thread id). Pure.
+ */
+export function commentHunkHash(entry: AllCommentEntry, files: FileView[]): string | null {
+  for (const file of files) {
+    for (const hunk of file.hunks) {
+      if (entry.localId !== null && hunk.comments.some((c) => c.id === entry.localId)) return hunk.hash;
+      if (entry.githubId !== null && hunk.githubThreads.some((t) => t.root.githubId === entry.githubId)) return hunk.hash;
+    }
+  }
+  return null;
+}
+
+/**
+ * What clicking a comment row in the All-comments panel should do, given the
+ * files for the whole selected range (`rangeFiles`) and the subset currently
+ * rendered after view toggles (`renderedFiles`):
+ * - `scroll` — it's already on screen; just scroll to it.
+ * - `reveal` — it belongs to the current range but a view toggle (or an
+ *   auto-collapsed viewed hunk) is hiding it; temporarily reveal that hunk,
+ *   then scroll. Carries the hunk hash to reveal. The selected range is never
+ *   changed.
+ * - `out-of-range` — it isn't in the current range at all; honouring it would
+ *   require changing the range, so the caller offers to open it in a new tab.
+ *
+ * Pure — reads only its arguments.
+ */
+export type CommentClickAction =
+  | { kind: "scroll" }
+  | { kind: "reveal"; hunkHash: string }
+  | { kind: "out-of-range" };
+
+/** Classify a comment-row click into a {@link CommentClickAction}. */
+export function classifyCommentClick(
+  entry: AllCommentEntry,
+  rangeFiles: FileView[],
+  renderedFiles: FileView[],
+): CommentClickAction {
+  if (commentVisibleInDiff(entry, renderedFiles)) return { kind: "scroll" };
+  const hunkHash: string | null = commentHunkHash(entry, rangeFiles);
+  if (hunkHash !== null) return { kind: "reveal", hunkHash };
+  return { kind: "out-of-range" };
+}

package/src/web/lib/composerKeys.ts

@@ -0,0 +1,24 @@
+/** The subset of a keyboard event the composer cares about. */
+export interface ComposerKey {
+  /** `KeyboardEvent.key` (e.g. "Enter", "Escape"). */
+  key: string;
+  /** Whether the Command key (macOS) is held. */
+  metaKey: boolean;
+  /** Whether the Control key is held. */
+  ctrlKey: boolean;
+}
+
+/** What a keypress in the composer should do. */
+export type ComposerIntent = "submit" | "cancel" | null;
+
+/**
+ * Map a keydown in a comment composer to an action. Cmd/Ctrl+Enter submits
+ * (plain Enter stays a newline, as expected in a multi-line body); Escape
+ * cancels. Anything else is `null` (let the textarea handle it). Pure — reads
+ * only the passed fields, mutates nothing.
+ */
+export function composerKeyIntent(event: ComposerKey): ComposerIntent {
+  if (event.key === "Enter" && (event.metaKey || event.ctrlKey)) return "submit";
+  if (event.key === "Escape") return "cancel";
+  return null;
+}

package/src/web/lib/dedupeResults.ts

@@ -0,0 +1,37 @@
+import type { CodeResult } from "@/services/symbols.ts";
+
+/** Combine two optional scope labels into a comma-separated, de-duplicated string. */
+function mergeScopes(a: string | undefined, b: string | undefined): string | undefined {
+  const parts: string[] = [];
+  for (const s of [a, b]) {
+    if (s !== undefined && s !== "" && !parts.includes(s)) parts.push(s);
+  }
+  return parts.length === 0 ? undefined : parts.join(", ");
+}
+
+/**
+ * Merge results that share the same `(path, line)` into a single item, joining
+ * their distinct `scope` labels. The same physical line can be reported more
+ * than once — e.g. a usage that falls inside both a class and one of its
+ * methods — and should appear once with the scopes combined.
+ *
+ * Preserves first-seen order and never mutates the input array or its items.
+ *
+ * @param results - The raw result list (possibly containing duplicate lines).
+ */
+export function dedupeResults(results: readonly CodeResult[]): CodeResult[] {
+  const byKey = new Map<string, CodeResult>();
+  const out: CodeResult[] = [];
+  for (const r of results) {
+    const key = `${r.path}:${r.line}`;
+    const existing = byKey.get(key);
+    if (existing === undefined) {
+      const copy: CodeResult = { ...r };
+      byKey.set(key, copy);
+      out.push(copy);
+    } else {
+      existing.scope = mergeScopes(existing.scope, r.scope);
+    }
+  }
+  return out;
+}

package/src/web/lib/diffMarks.ts

@@ -0,0 +1,81 @@
+import type { CharRange } from "@/domain/diff.ts";
+
+/** Opening tag for a highlighted changed run. */
+const MARK_OPEN = '<mark class="diff-word">';
+/** Closing tag for a highlighted changed run. */
+const MARK_CLOSE = "</mark>";
+
+/** A unit of already-highlighted HTML: a tag, an entity, or a literal char. */
+interface Token {
+  /** The raw HTML slice. */
+  html: string;
+  /** How many plain-text characters this token represents (0 for tags). */
+  width: number;
+}
+
+/**
+ * Overlay word-diff highlighting onto already-syntax-highlighted HTML: wrap the
+ * plain-text character ranges in `<mark class="diff-word">`, splitting so the
+ * mark never crosses a syntax-highlight tag boundary (it is closed before every
+ * tag and reopened after, keeping the markup well-nested). Pure — HTML in, HTML
+ * out.
+ *
+ * @param html   - One line of syntax-highlighted HTML (from `highlightToHtml`).
+ * @param ranges - Changed character ranges as offsets into the *plain* text.
+ */
+export function applyDiffMarks(html: string, ranges: CharRange[]): string {
+  if (ranges.length === 0) return html;
+  let out = "";
+  let offset = 0;
+  let markOpen = false;
+  for (const token of tokenize(html)) {
+    if (token.width === 0) {
+      if (markOpen) { out += MARK_CLOSE; markOpen = false; }
+      out += token.html;
+      continue;
+    }
+    const inRange = isInRange(offset, ranges);
+    if (inRange && !markOpen) { out += MARK_OPEN; markOpen = true; }
+    else if (!inRange && markOpen) { out += MARK_CLOSE; markOpen = false; }
+    out += token.html;
+    offset += token.width;
+  }
+  if (markOpen) out += MARK_CLOSE;
+  return out;
+}
+
+/** Split highlighted HTML into tags (width 0), entities (width 1), and chars. */
+function tokenize(html: string): Token[] {
+  const tokens: Token[] = [];
+  let i = 0;
+  while (i < html.length) {
+    const ch = html[i];
+    if (ch === "<") {
+      const end = html.indexOf(">", i);
+      const stop = end === -1 ? html.length : end + 1;
+      tokens.push({ html: html.slice(i, stop), width: 0 });
+      i = stop;
+    } else if (ch === "&") {
+      const entity = matchEntity(html, i);
+      tokens.push({ html: entity, width: 1 });
+      i += entity.length;
+    } else {
+      tokens.push({ html: ch ?? "", width: 1 });
+      i += 1;
+    }
+  }
+  return tokens;
+}
+
+/** Match an HTML entity starting at `i`, or the bare `&` if it is not one. */
+function matchEntity(html: string, i: number): string {
+  const semi = html.indexOf(";", i);
+  if (semi === -1) return "&";
+  const body = html.slice(i + 1, semi);
+  return /^#?[a-zA-Z0-9]+$/.test(body) ? html.slice(i, semi + 1) : "&";
+}
+
+/** Whether a plain-text offset falls within any changed range. */
+function isInRange(offset: number, ranges: CharRange[]): boolean {
+  return ranges.some((r) => offset >= r.start && offset < r.end);
+}

package/src/web/lib/fileStatus.ts

@@ -0,0 +1,12 @@
+import type { FileStatus } from "@/domain/diff.ts";
+
+/**
+ * The visual variant class for a file's diff status, used to colour the file
+ * tree's status icon. `renamed` shares the neutral "modified" treatment since a
+ * rename is a content change rather than an add/remove.
+ */
+export function fileStatusClass(status: FileStatus): "added" | "deleted" | "modified" {
+  if (status === "added") return "added";
+  if (status === "deleted") return "deleted";
+  return "modified";
+}

package/src/web/lib/filterCodeResults.ts

@@ -0,0 +1,42 @@
+import type { CodeResult } from "@/services/symbols.ts";
+
+/** Client-side filter options for a list of code results. */
+export interface CodeResultFilters {
+  /** Case-insensitive substring the file path must contain. */
+  pathText?: string;
+  /**
+   * Case-insensitive substring the code must contain — matched against the
+   * matched line, the definition body, and the before/after context lines.
+   */
+  codeText?: string;
+  /** When true, drop results the backend flagged as test/generated. */
+  excludeTestsGenerated?: boolean;
+}
+
+/** Whether any of a result's code text contains `needle` (case-insensitive). */
+function codeContains(r: CodeResult, needle: string): boolean {
+  const haystacks: string[] = [r.matched, r.body ?? "", ...r.before, ...r.after];
+  return haystacks.some((h) => h.toLowerCase().includes(needle));
+}
+
+/**
+ * Filter code results by path substring, code substring, and an
+ * exclude-tests/generated toggle. All active filters combine with AND.
+ * Purely derives a new array; never mutates the input.
+ *
+ * @param results - The full result list.
+ * @param filters - The active filter options (any subset).
+ */
+export function filterCodeResults(
+  results: readonly CodeResult[],
+  filters: CodeResultFilters,
+): CodeResult[] {
+  const pathNeedle = filters.pathText?.toLowerCase() ?? "";
+  const codeNeedle = filters.codeText?.toLowerCase() ?? "";
+  return results.filter((r) => {
+    if (filters.excludeTestsGenerated === true && r.testOrGenerated) return false;
+    if (pathNeedle !== "" && !r.path.toLowerCase().includes(pathNeedle)) return false;
+    if (codeNeedle !== "" && !codeContains(r, codeNeedle)) return false;
+    return true;
+  });
+}

package/src/web/lib/filterPrs.ts

@@ -0,0 +1,38 @@
+/** The minimal PR shape the picker filter needs. */
+export interface FilterablePr {
+  /** Repository owner / organisation. */
+  owner: string;
+  /** Repository name. */
+  repo: string;
+  /** Pull request number. */
+  number: number;
+  /** PR title. */
+  title: string;
+  /** GitHub login of the author (absent for already-loaded PRs). */
+  author?: string;
+}
+
+/**
+ * Case-insensitively filter PRs by a free-text query. A PR matches when the
+ * query (trimmed) is a substring of any of: `owner`, `repo`, `owner/repo`, the
+ * title, the author, or the number (with or without a leading `#`). A blank
+ * query returns every PR. The input array is never mutated.
+ */
+export function filterPrs<T extends FilterablePr>(query: string, prs: readonly T[]): T[] {
+  const q: string = query.trim().toLowerCase();
+  if (q.length === 0) return [...prs];
+  return prs.filter((pr) => haystack(pr).some((field) => field.includes(q)));
+}
+
+/** All lowercased fields of a PR that the query is tested against. */
+function haystack(pr: FilterablePr): string[] {
+  return [
+    pr.owner,
+    pr.repo,
+    `${pr.owner}/${pr.repo}`,
+    pr.title,
+    pr.author ?? "",
+    `#${pr.number}`,
+    String(pr.number),
+  ].map((f) => f.toLowerCase());
+}

package/src/web/lib/highlight.ts

@@ -0,0 +1,40 @@
+import hljs from "highlight.js";
+
+/** File-extension → highlight.js language name. */
+const EXT_LANG: Record<string, string> = {
+  ts: "typescript", tsx: "typescript", mts: "typescript", cts: "typescript",
+  js: "javascript", jsx: "javascript", mjs: "javascript", cjs: "javascript",
+  json: "json", css: "css", scss: "scss", html: "xml", xml: "xml",
+  md: "markdown", py: "python", rs: "rust", go: "go", sh: "bash", bash: "bash",
+  yml: "yaml", yaml: "yaml", sql: "sql", java: "java", rb: "ruby", php: "php",
+};
+
+/** The highlight.js language for a path, or undefined if unknown. */
+export function languageForPath(path: string): string | undefined {
+  const dot: number = path.lastIndexOf(".");
+  if (dot === -1) return undefined;
+  return EXT_LANG[path.slice(dot + 1).toLowerCase()];
+}
+
+/** Escape HTML special characters. */
+function escapeHtml(text: string): string {
+  return text
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;");
+}
+
+/**
+ * Return highlighted HTML for a line of code. Falls back to escaped plain text
+ * when the language is unknown or highlighting fails.
+ */
+export function highlightToHtml(code: string, language: string | undefined): string {
+  if (language && hljs.getLanguage(language)) {
+    try {
+      return hljs.highlight(code, { language }).value;
+    } catch {
+      return escapeHtml(code);
+    }
+  }
+  return escapeHtml(code);
+}

package/src/web/lib/identifierMenu.ts

@@ -0,0 +1,41 @@
+import type { DiffLine } from "@/domain/diff.ts";
+import type { SearchSide } from "@/web/state/useCodeSearch.ts";
+
+/** Regex matching a single lookup-able identifier token (JS-like). */
+const IDENTIFIER = /^[A-Za-z_$][\w$]*$/;
+
+/**
+ * Whether `term` is a single valid identifier we can look up (no dots, calls,
+ * spaces, or leading digits). The menu only opens for such tokens.
+ */
+export function isIdentifier(term: string): boolean {
+  return IDENTIFIER.test(term);
+}
+
+/**
+ * The repo-relative file path encoded in a `.file-section` element id
+ * (`file-<path>`), or "" when the id is not a file section. Only the leading
+ * `file-` prefix is stripped, so paths that themselves contain `file-` survive.
+ */
+export function fileFromSectionId(sectionId: string): string {
+  const prefix = "file-";
+  return sectionId.startsWith(prefix) ? sectionId.slice(prefix.length) : "";
+}
+
+/**
+ * Which checkout a diff line belongs to: a deleted line only exists on the base,
+ * so a symbol selected there defaults the lookup to base; added and context
+ * lines default to head (context is identical on both, head is the useful one).
+ */
+export function sideForLineKind(kind: DiffLine["kind"]): SearchSide {
+  return kind === "del" ? "base" : "head";
+}
+
+/**
+ * Interpret a `data-side` attribute stamped on a code cell. Only the explicit
+ * value "base" selects base; anything else (including a missing attribute)
+ * defaults to head.
+ */
+export function parseDataSide(value: string | null): SearchSide {
+  return value === "base" ? "base" : "head";
+}

package/src/web/lib/lineSelection.ts

@@ -0,0 +1,48 @@
+import type { DiffLine } from "@/domain/diff.ts";
+import type { DiffSide } from "@/domain/hash.ts";
+
+/** The anchor data for a (possibly multi-line) comment selection. */
+export interface LinesAnchor {
+  /** Which side the comment is on. */
+  side: DiffSide;
+  /** Exact head/base text of the selected same-side lines, newline-joined. */
+  lineText: string;
+  /** First selected line number on the chosen side. */
+  lineNo: number;
+  /** Last selected line number on the chosen side. */
+  endLineNo: number;
+}
+
+/** Whether a line participates on a given side. */
+function onSide(line: DiffLine, side: DiffSide): boolean {
+  return side === "RIGHT" ? line.kind === "add" || line.kind === "ctx" : line.kind === "del" || line.kind === "ctx";
+}
+
+/**
+ * Derive the comment anchor for a selected range of diff lines. Chooses the
+ * head (RIGHT) side unless the selection is deletions only, then joins the
+ * text of the selected lines that belong to that side.
+ *
+ * @returns The anchor, or null if the selection has no line on the chosen side.
+ */
+export function buildLinesAnchor(lines: DiffLine[], startIdx: number, endIdx: number): LinesAnchor | null {
+  const a: number = Math.min(startIdx, endIdx);
+  const b: number = Math.max(startIdx, endIdx);
+  const selected: DiffLine[] = lines.slice(a, b + 1);
+  const hasAdd: boolean = selected.some((l) => l.kind === "add");
+  const hasDel: boolean = selected.some((l) => l.kind === "del");
+  const side: DiffSide = !hasAdd && hasDel ? "LEFT" : "RIGHT";
+
+  const sideLines: DiffLine[] = selected.filter((l) => onSide(l, side));
+  const first: DiffLine | undefined = sideLines[0];
+  const last: DiffLine | undefined = sideLines[sideLines.length - 1];
+  if (!first || !last) return null;
+
+  const num = (l: DiffLine): number => (side === "RIGHT" ? l.newNo : l.oldNo) ?? 0;
+  return {
+    side,
+    lineText: sideLines.map((l) => l.text).join("\n"),
+    lineNo: num(first),
+    endLineNo: num(last),
+  };
+}

package/src/web/lib/navRouting.ts

@@ -0,0 +1,40 @@
+import type { CodeResult } from "@/services/symbols.ts";
+import type { MenuOp, SearchSide } from "@/web/state/useCodeSearch.ts";
+import type { NavFrame } from "./navStack.ts";
+
+/** Human label for a lookup op, for the results-frame header. */
+export function opLabel(op: MenuOp): string {
+  if (op === "search") return "Search";
+  return op === "usages" ? "Usages" : "Definition";
+}
+
+/**
+ * The frame to push after a lookup completes. An *unscoped* single-result
+ * Definition jumps straight to the definition (a `file` frame); everything else
+ * — Usages, Search, multi- or zero-result Definition, and any *scoped* lookup —
+ * shows the shared results list (a `results` frame, which renders the empty
+ * state and the scope chip + broaden action). A scoped single-result Definition
+ * deliberately stays a results frame so the "search everywhere" broaden control
+ * is reachable.
+ *
+ * @param op - The lookup op that ran.
+ * @param term - The looked-up term / query.
+ * @param side - The checkout side the lookup ran against.
+ * @param sha - The SHA the results were found at.
+ * @param results - The results returned.
+ * @param file - The file the lookup was scoped to ("" means repo-wide).
+ */
+export function frameForLookup(
+  op: MenuOp,
+  term: string,
+  side: SearchSide,
+  sha: string,
+  results: CodeResult[],
+  file: string,
+): NavFrame {
+  if (op === "definition" && results.length === 1 && file === "") {
+    const r = results[0]!;
+    return { kind: "file", path: r.path, sha, line: r.line };
+  }
+  return { kind: "results", op, term, side, sha, scopeFile: file, results };
+}

package/src/web/lib/navStack.ts

@@ -0,0 +1,109 @@
+import type { CodeResult } from "@/services/symbols.ts";
+import type { MenuOp, SearchSide } from "@/web/state/useCodeSearch.ts";
+
+/** A diff frame: a file's split base/head view over the navigator's range. */
+export interface DiffNavFrame {
+  /** Frame discriminant. */
+  kind: "diff";
+  /** Repo-relative file path. */
+  path: string;
+  /** 1-based line to center/flash, or null to open at the top. */
+  anchorLine?: number | null;
+}
+
+/** A file frame: a single-version file view at one commit, centered on a line. */
+export interface FileNavFrame {
+  /** Frame discriminant. */
+  kind: "file";
+  /** Repo-relative file path. */
+  path: string;
+  /** Commit SHA to read the file at. */
+  sha: string;
+  /** 1-based line to center and flash. */
+  line: number;
+}
+
+/** A results frame: a list of code results from a lookup/search. */
+export interface ResultsNavFrame {
+  /** Frame discriminant. */
+  kind: "results";
+  /** The lookup op that produced the results. */
+  op: MenuOp;
+  /** The looked-up term / query. */
+  term: string;
+  /** Which checkout side the lookup ran against. */
+  side: SearchSide;
+  /** The SHA the results were found at (for opening file frames). */
+  sha: string;
+  /** The file the lookup was scoped to (a "" means repo-wide). */
+  scopeFile: string;
+  /** The results to list. */
+  results: CodeResult[];
+}
+
+/** One frame in the navigator's Back/Forward history. */
+export type NavFrame = DiffNavFrame | FileNavFrame | ResultsNavFrame;
+
+/** The navigator's history: the frame list plus the current position in it. */
+export interface NavStack {
+  /** The frames, oldest → newest. */
+  stack: NavFrame[];
+  /** Index of the currently shown frame. */
+  index: number;
+}
+
+/** An action the {@link navStackReducer} understands. */
+export type NavStackAction =
+  | { type: "push"; frame: NavFrame }
+  | { type: "back" }
+  | { type: "forward" };
+
+/** A fresh history seeded with a single origin frame. */
+export function initNavStack(frame: NavFrame): NavStack {
+  return { stack: [frame], index: 0 };
+}
+
+/** The frame currently shown. */
+export function currentFrame(s: NavStack): NavFrame {
+  return s.stack[s.index]!;
+}
+
+/**
+ * A stable identity key for a frame: frames that show the same content share a
+ * key. Used to keep each visited frame mounted (so its scroll position survives
+ * Back/Forward) while giving React a distinct key per history entry.
+ */
+export function frameKey(frame: NavFrame): string {
+  if (frame.kind === "diff") return `diff:${frame.path}`;
+  if (frame.kind === "file") return `file:${frame.path}:${frame.sha}`;
+  return `results:${frame.op}:${frame.term}:${frame.side}:${frame.sha}`;
+}
+
+/** Whether there is an earlier frame to go Back to. */
+export function canGoBack(s: NavStack): boolean {
+  return s.index > 0;
+}
+
+/** Whether there is a later frame to go Forward to. */
+export function canGoForward(s: NavStack): boolean {
+  return s.index < s.stack.length - 1;
+}
+
+/**
+ * The navigator history reducer. `push` drops any forward history (frames after
+ * the current index) and appends the new frame as the current one; `back` /
+ * `forward` move the cursor, clamped to the ends. Never mutates its input.
+ */
+export function navStackReducer(state: NavStack, action: NavStackAction): NavStack {
+  switch (action.type) {
+    case "push": {
+      const kept = state.stack.slice(0, state.index + 1);
+      const stack = [...kept, action.frame];
+      return { stack, index: stack.length - 1 };
+    }
+    case "back":
+      return { stack: state.stack, index: Math.max(0, state.index - 1) };
+    case "forward":
+      return { stack: state.stack, index: Math.min(state.stack.length - 1, state.index + 1) };
+  }
+}