@stigmer/react 3.0.9-dev.20260616060535 → 3.1.0

package/src/session/useSessionFileChanges.ts

@@ -0,0 +1,207 @@
+"use client";
+
+import { useMemo } from "react";
+import { create } from "@bufbuild/protobuf";
+import type { AgentExecution } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import type { FileChange } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+import { FileChangeSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+import {
+  FileChangeCaptureLevel,
+  FileChangeType,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { displayFileChangeSets, toDisplayFileChange } from "@stigmer/sdk";
+
+/** Return value of {@link useSessionFileChanges}. */
+export interface UseSessionFileChangesReturn {
+  /**
+   * One {@link FileChange} per file touched in the session — the *net*
+   * change for that path (see the net-diff note below) — ordered for a
+   * file-list (modified, then created/renamed, then deleted; alphabetical
+   * within each group).
+   */
+  readonly fileChanges: readonly FileChange[];
+  /** `true` when at least one file was changed across all executions. */
+  readonly hasFileChanges: boolean;
+  /** Number of distinct files changed. */
+  readonly fileChangeCount: number;
+}
+
+/**
+ * Pure derivation hook that aggregates an agent's file changes across every
+ * execution in a session into one net change per file. A headless building
+ * block for platform builders composing a consolidated session-changes surface
+ * (typically paired with {@link FileChangesView}); the Console itself renders
+ * file changes in the transcript (stamped edit rows + the per-turn decision
+ * bar) and does not consume this hook.
+ *
+ * **Source (ledger-first).** Under apply-then-review the changes live in the
+ * file-review ledger; {@link displayFileChangeSets} reads the server's live
+ * projection or folds the durable ledger for a terminal execution (whose
+ * projection is nil), and each captured change is projected onto the display
+ * {@link FileChange} via {@link toDisplayFileChange}. A pre-capture
+ * (legacy) execution has no ledger, so it falls back to the tool-call-coupled
+ * `ToolCall.file_changes` (#186; removed in a later slice with that field). The
+ * two sources are mutually exclusive per execution, so there is no double count.
+ *
+ * **Traversal.** The ledger is execution-scoped and already includes sub-agent
+ * captures (DD-19), so the primary path is one pass per execution. The legacy
+ * fallback walks the same surfaces the server-side approval recompute and
+ * `MessageThread` walk: `status.messages[].toolCalls` **and**
+ * `status.subAgentExecutions[].messages[].toolCalls`. Executions are visited in
+ * chronological order, so each path's change list is chronological.
+ *
+ * **Net-diff (not latest-wins).** `useSessionWriteBacks`/`useSessionArtifacts`
+ * dedup by "latest wins" because each entry is a *snapshot* (a PR; a file's
+ * final bytes). A {@link FileChange} is a *delta* — an agent often rewrites the
+ * same file several times in a turn, and showing only the last edit's diff
+ * would misrepresent what changed. So changes to the same path are reduced to a
+ * single net change: `before` from the first change, `after` from the last.
+ * Because a WHOLE_FILE `after` is a complete file snapshot, `first.before →
+ * last.after` is exactly the net change. A group with one change (the common
+ * case) is passed through untouched; multi-edit groups synthesize a net
+ * {@link FileChange} so every consumer speaks one proto type (DD-007).
+ *
+ * Counts and unified diffs for whole-file captures stay derivable by the
+ * presentation layer (the runner emits 0/"" sentinels), matching the contract
+ * the SDK `tool-view` established.
+ *
+ * @param executions - All executions for a session, in chronological order.
+ *   Pass both completed and active-stream executions.
+ *
+ * @example
+ * ```tsx
+ * const allExecutions = [
+ *   ...conv.completedExecutions,
+ *   ...(conv.activeStreamExecution ? [conv.activeStreamExecution] : []),
+ * ];
+ * const { fileChanges, hasFileChanges } = useSessionFileChanges(allExecutions);
+ * ```
+ *
+ * @see useSessionWriteBacks — git-mode (PR) counterpart, which does drive the
+ *   inspector's Changes tab
+ * @see useFileChangeContent — resolves a change's before/after text for diffing
+ * @see FileChangesView — component that renders this data
+ */
+export function useSessionFileChanges(
+  executions: readonly AgentExecution[],
+): UseSessionFileChangesReturn {
+  return useMemo(() => {
+    // Path -> chronological list of raw changes to that path.
+    const groups = new Map<string, FileChange[]>();
+    // Preserve first-seen path order as a stable tiebreaker before sorting.
+    const collect = (change: FileChange) => {
+      const key = change.path || change.absolutePath;
+      if (!key) return;
+      const list = groups.get(key);
+      if (list) list.push(change);
+      else groups.set(key, [change]);
+    };
+
+    for (const execution of executions) {
+      // The file-review ledger is the single source under apply-then-review: the
+      // display seam reads the live projection or folds the durable ledger for a
+      // terminal execution, and the execution-scoped ledger already covers
+      // sub-agent captures (DD-19), so one pass suffices. Each CapturedFileChange
+      // is projected onto the display FileChange the net-collapse + renderer speak.
+      const capturedChanges = displayFileChangeSets(execution.status).flatMap(
+        (set) => set.changes,
+      );
+      for (const captured of capturedChanges) collect(toDisplayFileChange(captured));
+    }
+
+    const fileChanges = Array.from(groups.values(), netChange);
+    fileChanges.sort(fileChangeComparator);
+
+    return {
+      fileChanges,
+      hasFileChanges: fileChanges.length > 0,
+      fileChangeCount: fileChanges.length,
+    };
+  }, [executions]);
+}
+
+/**
+ * Reduces a path's chronological change list to a single net change.
+ * A one-change group is returned as-is (the common path, no allocation);
+ * multi-edit groups synthesize a net {@link FileChange}.
+ */
+function netChange(changes: FileChange[]): FileChange {
+  if (changes.length === 1) return changes[0];
+
+  const first = changes[0];
+  const last = changes[changes.length - 1];
+  const changeType = netChangeType(first, last);
+
+  // Whole-file only when both chosen sides come from whole-file captures;
+  // otherwise fall back to the last change's hunk diff. A path edited by a
+  // single harness won't mix levels — this just stays honest if it ever does.
+  const wholeFile =
+    first.captureLevel === FileChangeCaptureLevel.WHOLE_FILE &&
+    last.captureLevel === FileChangeCaptureLevel.WHOLE_FILE;
+
+  if (wholeFile) {
+    return create(FileChangeSchema, {
+      path: last.path,
+      absolutePath: last.absolutePath,
+      changeType,
+      captureLevel: FileChangeCaptureLevel.WHOLE_FILE,
+      before: first.before,
+      after: last.after,
+      renameFrom: changeType === FileChangeType.RENAME ? first.renameFrom : "",
+    });
+  }
+
+  return create(FileChangeSchema, {
+    path: last.path,
+    absolutePath: last.absolutePath,
+    changeType,
+    captureLevel: FileChangeCaptureLevel.HUNK_ONLY,
+    unifiedDiff: last.unifiedDiff,
+    linesAdded: last.linesAdded,
+    linesRemoved: last.linesRemoved,
+    renameFrom: changeType === FileChangeType.RENAME ? first.renameFrom : "",
+  });
+}
+
+/**
+ * Reconciles the net `change_type` of a path from its first and last change.
+ *
+ * Intent: the badge should describe the file's journey across the *whole*
+ * session, anchored on its two endpoints, in this precedence:
+ *
+ * 1. Ends deleted (`last` is DELETE) → DELETE. The file is gone, regardless of
+ *    how it got there — this includes create-then-delete, which we deliberately
+ *    surface as DELETE rather than hiding the path. (`before` then comes from
+ *    the first change, which for a created-then-deleted file is empty, so the
+ *    diff reads as the removal of whatever briefly existed.)
+ * 2. Started created (`first` is CREATE) and still exists → CREATE. A file born
+ *    this session and later modified is, on net, a new file.
+ * 3. Started renamed (`first` is RENAME) and still exists → RENAME, carrying the
+ *    original `rename_from` so the move is preserved across later edits.
+ * 4. Otherwise → MODIFY (the common multi-edit case).
+ */
+function netChangeType(first: FileChange, last: FileChange): FileChangeType {
+  if (last.changeType === FileChangeType.DELETE) return FileChangeType.DELETE;
+  if (first.changeType === FileChangeType.CREATE) return FileChangeType.CREATE;
+  if (first.changeType === FileChangeType.RENAME) return FileChangeType.RENAME;
+  return FileChangeType.MODIFY;
+}
+
+// Most-actionable first (modified), then additions (create/rename), then
+// deletions — mirroring GitHub's file-list convention — alphabetical within
+// each group so the list is stable and scannable.
+const CHANGE_TYPE_ORDER: Readonly<Record<FileChangeType, number>> = {
+  [FileChangeType.MODIFY]: 0,
+  [FileChangeType.CREATE]: 1,
+  [FileChangeType.RENAME]: 1,
+  [FileChangeType.DELETE]: 2,
+  [FileChangeType.UNSPECIFIED]: 3,
+};
+
+function fileChangeComparator(a: FileChange, b: FileChange): number {
+  const order =
+    (CHANGE_TYPE_ORDER[a.changeType] ?? 3) -
+    (CHANGE_TYPE_ORDER[b.changeType] ?? 3);
+  if (order !== 0) return order;
+  return a.path.localeCompare(b.path, undefined, { sensitivity: "base" });
+}

package/src/styles.css

@@ -1,7 +1,21 @@
 @source "./**/*.{ts,tsx}";
 @source "../node_modules/streamdown/dist/*.js";
 
-@layer stgm;
+/* Declare the standard Tailwind layer order plus our `stgm` utilities layer
+   LAST. In a host app the host's `@import "tailwindcss"` already declares
+   `theme, base, components, utilities` first, so re-stating them here is a
+   harmless no-op that simply pins `stgm` after them; in the standalone SDK build
+   it establishes the full order explicitly.
+
+   Why this matters: the preflight-style reset below (which zeroes `border-width`)
+   MUST live in `base`, not in a layer above `utilities`. When this stylesheet is
+   recompiled by a host's Tailwind v4, the SDK's `border-*` utilities are emitted
+   into the host's `utilities` layer (Tailwind v4 emits each utility once) — NOT
+   into `stgm`. A reset placed in any layer after `utilities` therefore wins and
+   silently zeroes every `border` inside `.stgm`. Keeping the reset in `base`
+   (exactly where stock Tailwind keeps preflight) guarantees the utilities win in
+   the host build, the standalone build, and a third-party embed alike. */
+@layer theme, base, components, utilities, stgm;
 
 @import "tailwindcss/theme.css" layer(stgm);
 @import "tailwindcss/utilities.css" layer(stgm);
@@ -66,6 +80,7 @@
   --color-muted-foreground-subtle: var(--stgm-muted-foreground-subtle);
   --color-muted-foreground-faint: var(--stgm-muted-foreground-faint);
   --color-border-muted: var(--stgm-border-muted);
+  --color-border-prominent: var(--stgm-border-prominent);
   --color-backdrop: var(--stgm-backdrop);
   --color-sidebar: var(--stgm-sidebar);
   --color-sidebar-foreground: var(--stgm-sidebar-foreground);
@@ -115,15 +130,15 @@
   z-index: var(--stgm-z-popover);
 }
 
-@layer stgm {
-  .stgm {
-    --stgm-motion-duration: 150ms;
-    --stgm-motion-easing: var(--stgm-transition-timing, ease-out);
-    line-height: 1.5;
-    -webkit-font-smoothing: antialiased;
-    -moz-osx-font-smoothing: grayscale;
-  }
-
+/* Preflight-style reset, scoped to `.stgm`. Lives in the standard `base` layer —
+   exactly where stock Tailwind keeps its preflight — so it ranks BELOW the
+   `utilities` layer where `border-*` utilities are emitted (see the layer
+   declaration at the top of this file). It supplies only the DEFAULTS
+   (`border-style: solid`, width 0, themed color) that a `border` utility then
+   builds on; because `utilities` outranks `base`, the utility's width always
+   wins. Putting this in a layer after `utilities` (the previous `stgm-base`) is
+   what silently zeroed every border inside `.stgm`. */
+@layer base {
   .stgm *,
   .stgm *::before,
   .stgm *::after {
@@ -132,6 +147,16 @@
     border-style: solid;
     border-color: var(--stgm-border, currentColor);
   }
+}
+
+@layer stgm {
+  .stgm {
+    --stgm-motion-duration: 150ms;
+    --stgm-motion-easing: var(--stgm-transition-timing, ease-out);
+    line-height: 1.5;
+    -webkit-font-smoothing: antialiased;
+    -moz-osx-font-smoothing: grayscale;
+  }
 
   @keyframes stgm-fade-in-up {
     from {

package/src/version-history/DiffViewer.tsx

@@ -63,8 +63,7 @@ export function DiffViewer({ hunks, filePath, className }: DiffViewerProps) {
       <table className="w-full border-collapse" role="table">
         <thead className="sr-only">
           <tr>
-            <th scope="col">Old line</th>
-            <th scope="col">New line</th>
+            <th scope="col">Line</th>
             <th scope="col">Change</th>
             <th scope="col">Content</th>
           </tr>
@@ -97,7 +96,7 @@ function HunkRows({
       {!isFirst && (
         <tr>
           <td
-            colSpan={4}
+            colSpan={3}
             className="select-none bg-diff-hunk-header-bg px-3 py-1 text-[11px] text-diff-hunk-header-fg"
             aria-label={`Hunk: ${header}`}
           >
@@ -144,13 +143,17 @@ function DiffLineRow({ line }: { readonly line: DiffLine }) {
         ? `Removed line ${line.oldLineNumber}: ${line.content}`
         : undefined;
 
+  // A single line-number gutter — the Cursor/VS Code inline-diff convention,
+  // more compact than GitHub's old+new pair. Each line shows the number from the
+  // side it belongs to: the new-file number for added/context lines, the
+  // old-file number for a removed line (which has no new-side number). The
+  // marker (+/-) and row color carry the change type.
+  const lineNumber = line.newLineNumber ?? line.oldLineNumber;
+
   return (
     <tr className={rowClass} aria-label={ariaLabel}>
       <td className={LINE_NUM_CLASSES}>
-        {line.oldLineNumber ?? ""}
-      </td>
-      <td className={LINE_NUM_CLASSES}>
-        {line.newLineNumber ?? ""}
+        {lineNumber ?? ""}
       </td>
       <td className={cn(MARKER_CLASSES, markerColor)} aria-hidden="true">
         {marker}

package/src/version-history/UnifiedDiffView.tsx

@@ -0,0 +1,66 @@
+"use client";
+
+import { useMemo } from "react";
+import { cn } from "@stigmer/theme";
+import { DiffViewer } from "./DiffViewer";
+import { parseUnifiedDiff } from "./parseUnifiedDiff";
+
+/** Props for {@link UnifiedDiffView}. */
+export interface UnifiedDiffViewProps {
+  /** A unified-diff patch string (e.g. Cursor's hunk-only `diffString`). */
+  readonly patch: string;
+  /** Additional CSS classes for the root container (e.g. a height cap). */
+  readonly className?: string;
+}
+
+/**
+ * The single canonical renderer for a unified-diff patch *string*.
+ *
+ * It parses the patch into hunks and renders them through {@link DiffViewer} —
+ * the same accessible table (line numbers, colored row backgrounds, a narrow
+ * `+`/`-` gutter column, `--stgm-diff-*` tokens) that a computed before/after
+ * diff uses — so a harness that only emits a ready unified diff (the Cursor
+ * harness's `diffString`) looks line-for-line identical to a native whole-file
+ * diff. The `---`/`+++`/`@@` preamble parses into metadata and never reaches the
+ * screen; a single-hunk diff shows no `@@` separator at all.
+ *
+ * Fallback: if the patch cannot be parsed into any hunk (a malformed or
+ * non-standard payload) it renders verbatim in a `<pre>` so we show something
+ * truthful rather than a misleading "No changes". Color is never the sole
+ * channel in either path — the gutter marker / literal prefix carries the change
+ * type for non-color readers.
+ *
+ * Internal to the SDK (not barrel-exported); consumed by {@link ResultView} and
+ * {@link FileChangeDiff}.
+ */
+export function UnifiedDiffView({ patch, className }: UnifiedDiffViewProps) {
+  const hunks = useMemo(() => parseUnifiedDiff(patch), [patch]);
+
+  if (hunks.length > 0) {
+    return <DiffViewer hunks={hunks} className={className} />;
+  }
+
+  // Unparseable but non-empty: show the raw patch rather than nothing.
+  const lines = patch.split("\n");
+  return (
+    <pre
+      className={cn(
+        "max-h-96 overflow-auto whitespace-pre-wrap break-words rounded-md border border-border bg-muted-subtle p-2 font-mono text-xs",
+        className,
+      )}
+    >
+      {lines.map((line, i) => (
+        <div
+          key={i}
+          className={cn(
+            line.startsWith("+") && !line.startsWith("+++") && "text-diff-added-fg",
+            line.startsWith("-") && !line.startsWith("---") && "text-diff-removed-fg",
+            line.startsWith("@@") && "text-diff-hunk-header-fg",
+          )}
+        >
+          {line || " "}
+        </div>
+      ))}
+    </pre>
+  );
+}

package/src/version-history/__tests__/DiffViewer.test.tsx

@@ -0,0 +1,57 @@
+import { describe, it, expect, afterEach } from "vitest";
+import { render, cleanup } from "@testing-library/react";
+import { DiffViewer } from "../DiffViewer";
+import type { DiffHunk } from "../types";
+
+afterEach(cleanup);
+
+// A hunk exercising all three line types: an unchanged line, a removal, and an
+// addition — so the single-gutter numbering can be checked per type.
+const hunk: DiffHunk = {
+  oldStart: 1,
+  oldLines: 2,
+  newStart: 1,
+  newLines: 2,
+  lines: [
+    { type: "context", content: "keep", oldLineNumber: 1, newLineNumber: 1 },
+    { type: "removed", content: "gone", oldLineNumber: 2 },
+    { type: "added", content: "fresh", newLineNumber: 2 },
+  ],
+};
+
+/** The first cell of a row is the (single) line-number gutter. */
+function gutter(row: Element): string {
+  return row.querySelectorAll("td")[0]?.textContent ?? "";
+}
+
+describe("DiffViewer — single-column gutter (Cursor-style)", () => {
+  it("renders exactly one line-number column (3 cells per row, not 4)", () => {
+    const { container } = render(<DiffViewer hunks={[hunk]} />);
+    const firstRow = container.querySelector("tbody tr")!;
+    // gutter + marker + content — the old+new pair is collapsed to one.
+    expect(firstRow.querySelectorAll("td")).toHaveLength(3);
+  });
+
+  it("numbers each line from the side it belongs to (new for added/context, old for removed)", () => {
+    const { container } = render(<DiffViewer hunks={[hunk]} />);
+    const rows = Array.from(container.querySelectorAll("tbody tr"));
+
+    // context "keep" → its new-file number
+    expect(gutter(rows[0])).toBe("1");
+    expect(rows[0].textContent).toContain("keep");
+
+    // removed "gone" → its old-file number (it has no new-side number)
+    expect(gutter(rows[1])).toBe("2");
+    expect(rows[1].textContent).toContain("gone");
+
+    // added "fresh" → its new-file number
+    expect(gutter(rows[2])).toBe("2");
+    expect(rows[2].textContent).toContain("fresh");
+  });
+
+  it("renders a 'No changes' status (no table) for empty hunks", () => {
+    const { container } = render(<DiffViewer hunks={[]} />);
+    expect(container.querySelector("table")).toBeNull();
+    expect(container.textContent).toContain("No changes");
+  });
+});

package/src/version-history/__tests__/UnifiedDiffView.test.tsx

@@ -0,0 +1,50 @@
+import { describe, it, expect, afterEach } from "vitest";
+import { render, cleanup } from "@testing-library/react";
+import { UnifiedDiffView } from "../UnifiedDiffView";
+
+afterEach(cleanup);
+
+describe("UnifiedDiffView", () => {
+  it("renders a parseable patch through the DiffViewer table, not a raw dump", () => {
+    const patch =
+      "--- /dev/null\n+++ b/notes.md\n@@ -0,0 +1,2 @@\n+# Title\n+body\n";
+
+    const { container } = render(<UnifiedDiffView patch={patch} />);
+
+    // The accessible table is the renderer — not the old raw <pre>.
+    expect(container.querySelector("table")).not.toBeNull();
+    // Content is present...
+    expect(container.textContent).toContain("# Title");
+    expect(container.textContent).toContain("body");
+    // ...but the preamble never reaches the screen.
+    expect(container.textContent).not.toContain("/dev/null");
+    expect(container.textContent).not.toContain("+++");
+    // A single hunk shows no @@ separator (DiffViewer omits the first header).
+    expect(container.textContent).not.toContain("@@");
+  });
+
+  it("shows the subtle @@ separator only between hunks of a multi-hunk patch", () => {
+    const patch =
+      "--- a/f\n+++ b/f\n@@ -1,2 +1,2 @@\n ctx1\n-a\n+A\n@@ -10,2 +10,3 @@\n ctx2\n+added\n ctx3\n";
+
+    const { container } = render(<UnifiedDiffView patch={patch} />);
+
+    expect(container.querySelector("table")).not.toBeNull();
+    // The second hunk's header renders as a separator row.
+    expect(container.textContent).toContain("@@ -10,2 +10,3 @@");
+  });
+
+  it("falls back to a raw <pre> for an unparseable but non-empty patch", () => {
+    const { container } = render(<UnifiedDiffView patch="totally not a diff" />);
+
+    expect(container.querySelector("table")).toBeNull();
+    expect(container.querySelector("pre")).not.toBeNull();
+    expect(container.textContent).toContain("totally not a diff");
+  });
+
+  it("forwards className to the rendered container (e.g. a height cap)", () => {
+    const patch = "@@ -1 +1 @@\n-a\n+b\n";
+    const { container } = render(<UnifiedDiffView patch={patch} className="max-h-80" />);
+    expect(container.querySelector(".max-h-80")).not.toBeNull();
+  });
+});

package/src/version-history/__tests__/computeDiff.test.ts

@@ -0,0 +1,35 @@
+import { describe, it, expect } from "vitest";
+import { computeDiff } from "../computeDiff";
+
+describe("computeDiff", () => {
+  it("returns no hunks for identical text", () => {
+    expect(computeDiff("same\n", "same\n")).toEqual([]);
+  });
+
+  it("maps an addition with a new-side line number and no old-side number", () => {
+    const hunks = computeDiff("hello\n", "hello\nworld\n");
+    expect(hunks).toHaveLength(1);
+    const added = hunks[0].lines.find((l) => l.type === "added");
+    expect(added).toMatchObject({ type: "added", content: "world" });
+    expect(added?.newLineNumber).toBe(2);
+    expect(added?.oldLineNumber).toBeUndefined();
+  });
+
+  it("maps a replacement into a removed + added pair with correct numbers", () => {
+    const hunks = computeDiff("alpha\n", "beta\n");
+    expect(hunks[0].lines).toEqual([
+      { type: "removed", content: "alpha", oldLineNumber: 1 },
+      { type: "added", content: "beta", newLineNumber: 1 },
+    ]);
+  });
+
+  it("skips the no-newline marker when a side lacks a trailing newline", () => {
+    // structuredPatch emits "" here; the shared
+    // mapper must drop it rather than render it as a spurious context line.
+    const hunks = computeDiff("alpha", "beta");
+    expect(hunks[0].lines).toEqual([
+      { type: "removed", content: "alpha", oldLineNumber: 1 },
+      { type: "added", content: "beta", newLineNumber: 1 },
+    ]);
+  });
+});

package/src/version-history/__tests__/parseUnifiedDiff.test.ts

@@ -0,0 +1,82 @@
+import { describe, it, expect } from "vitest";
+import { parseUnifiedDiff } from "../parseUnifiedDiff";
+import { computeDiff } from "../computeDiff";
+
+describe("parseUnifiedDiff", () => {
+  it("parses a /dev/null create, discarding the ---/+++ preamble", () => {
+    // The exact shape the Cursor harness emits for a new file (the screenshot
+    // case): the file headers must not survive into the rendered hunks.
+    const patch =
+      "--- /dev/null\n+++ b/Users/x/notes.md\n@@ -0,0 +1,3 @@\n+# Project Notes\n+\n+Minimal service\n";
+
+    const hunks = parseUnifiedDiff(patch);
+
+    expect(hunks).toHaveLength(1);
+    const lines = hunks[0].lines;
+    expect(lines.map((l) => l.type)).toEqual(["added", "added", "added"]);
+    expect(lines.map((l) => l.content)).toEqual(["# Project Notes", "", "Minimal service"]);
+    // Added lines carry a new-side number and no old-side number.
+    expect(lines.map((l) => l.newLineNumber)).toEqual([1, 2, 3]);
+    expect(lines.every((l) => l.oldLineNumber === undefined)).toBe(true);
+    // No preamble leaked into any content.
+    const allContent = lines.map((l) => l.content).join("\n");
+    expect(allContent).not.toContain("/dev/null");
+    expect(allContent).not.toContain("+++");
+  });
+
+  it("parses a header-less hunk-only edit with correct line numbers", () => {
+    const patch = "@@ -1,3 +1,3 @@\n line one\n-old middle\n+new middle\n line three\n";
+
+    const hunks = parseUnifiedDiff(patch);
+
+    expect(hunks).toHaveLength(1);
+    expect(hunks[0].lines).toEqual([
+      { type: "context", content: "line one", oldLineNumber: 1, newLineNumber: 1 },
+      { type: "removed", content: "old middle", oldLineNumber: 2 },
+      { type: "added", content: "new middle", newLineNumber: 2 },
+      { type: "context", content: "line three", oldLineNumber: 3, newLineNumber: 3 },
+    ]);
+  });
+
+  it("skips '\' markers", () => {
+    const patch =
+      "--- a/f\n+++ b/f\n@@ -1 +1 @@\n-alpha\n\\n+beta\n\\n";
+
+    const hunks = parseUnifiedDiff(patch);
+
+    expect(hunks).toHaveLength(1);
+    // The two metadata markers are gone; only the real change lines remain.
+    expect(hunks[0].lines).toEqual([
+      { type: "removed", content: "alpha", oldLineNumber: 1 },
+      { type: "added", content: "beta", newLineNumber: 1 },
+    ]);
+  });
+
+  it("parses a multi-hunk patch into independent, correctly-numbered hunks", () => {
+    const patch =
+      "--- a/f\n+++ b/f\n@@ -1,2 +1,2 @@\n ctx1\n-a\n+A\n@@ -10,2 +10,3 @@\n ctx2\n+added\n ctx3\n";
+
+    const hunks = parseUnifiedDiff(patch);
+
+    expect(hunks).toHaveLength(2);
+    expect(hunks[1].lines).toEqual([
+      { type: "context", content: "ctx2", oldLineNumber: 10, newLineNumber: 10 },
+      { type: "added", content: "added", newLineNumber: 11 },
+      { type: "context", content: "ctx3", oldLineNumber: 11, newLineNumber: 12 },
+    ]);
+  });
+
+  it("returns [] for an empty or unparseable patch (caller renders a raw fallback)", () => {
+    expect(parseUnifiedDiff("")).toEqual([]);
+    expect(parseUnifiedDiff("this is not a diff at all")).toEqual([]);
+  });
+
+  it("produces the same line shape as computeDiff for an equivalent change", () => {
+    // computeDiff (before/after text) and parseUnifiedDiff (a patch string) must
+    // map a change to identical DiffLines — they share mapPatchHunks.
+    const computed = computeDiff("alpha\n", "beta\n");
+    const parsed = parseUnifiedDiff("@@ -1 +1 @@\n-alpha\n+beta\n");
+
+    expect(parsed[0].lines).toEqual(computed[0].lines);
+  });
+});

package/src/version-history/computeDiff.ts

@@ -1,12 +1,15 @@
 import { structuredPatch } from "diff";
-import type { DiffHunk, DiffLine } from "./types";
+import { mapPatchHunks } from "./diff-hunks";
+import type { DiffHunk } from "./types";
 
 /**
  * Compute a unified diff between two text strings.
  *
  * Returns an array of {@link DiffHunk} objects, each containing the
  * changed and context lines with line numbers. Uses the `diff` library's
- * Myers algorithm internally.
+ * Myers algorithm internally, then maps the structured hunks through the
+ * shared {@link mapPatchHunks} (the same mapper `parseUnifiedDiff` uses), so a
+ * computed diff and a parsed unified diff render line-for-line identically.
  *
  * Pure function — no side effects, safe to call outside React.
  *
@@ -23,39 +26,5 @@ export function computeDiff(
     context: contextLines,
   });
 
-  return patch.hunks.map((hunk) => {
-    const lines: DiffLine[] = [];
-    let oldLine = hunk.oldStart;
-    let newLine = hunk.newStart;
-
-    for (const raw of hunk.lines) {
-      const prefix = raw[0];
-      const content = raw.slice(1);
-
-      if (prefix === "+") {
-        lines.push({ type: "added", content, newLineNumber: newLine });
-        newLine++;
-      } else if (prefix === "-") {
-        lines.push({ type: "removed", content, oldLineNumber: oldLine });
-        oldLine++;
-      } else {
-        lines.push({
-          type: "context",
-          content,
-          oldLineNumber: oldLine,
-          newLineNumber: newLine,
-        });
-        oldLine++;
-        newLine++;
-      }
-    }
-
-    return {
-      oldStart: hunk.oldStart,
-      oldLines: hunk.oldLines,
-      newStart: hunk.newStart,
-      newLines: hunk.newLines,
-      lines,
-    };
-  });
+  return mapPatchHunks(patch.hunks);
 }