openclaw
diff --git a/‎docs/docs_map.md‎
Lines changed: 1 addition & 0 deletions b/‎docs/docs_map.md‎
Lines changed: 1 addition & 0 deletions
diff --git a/‎docs/tools/diffs.md‎
Lines changed: 4 additions & 0 deletions b/‎docs/tools/diffs.md‎
Lines changed: 4 additions & 0 deletions
diff --git a/‎extensions/diffs/README.md‎
Lines changed: 2 additions & 0 deletions b/‎extensions/diffs/README.md‎
Lines changed: 2 additions & 0 deletions
diff --git a/‎extensions/diffs/src/render.test.ts‎
Lines changed: 102 additions & 2 deletions b/‎extensions/diffs/src/render.test.ts‎
Lines changed: 102 additions & 2 deletions
@@ -9094,6 +9094,7 @@ Do not edit it by hand; run `pnpm docs:map:gen`.
   - H2: Syntax highlighting
   - H2: Output details contract
   - H3: Collapsed unchanged sections
+  - H3: Multi-file navigation
   - H2: Plugin defaults
   - H3: Persistent viewer URL config
   - H2: Security config
 
@@ -221,6 +221,10 @@ All successful results include `changed`: identical before/after input returns `
 
 The viewer shows rows like `N unmodified lines`. Expand controls only appear when the rendered diff has expandable context data (typical for before/after input). Many unified patches omit context bodies in their hunks, so the row can appear without an expand control -- expected, not a bug. `expandUnchanged` only applies when expandable context exists.
 
+### Multi-file navigation
+
+Patches that touch more than one file start with a changed-files summary card: total `+N` / `-N` counts, per-file counts, added/deleted/renamed badges, and anchor links that jump to each file. Rendered PNG/PDF files keep the per-file header counts but drop the interactive view toggles, since those are dead controls in a static file.
+
 ## Plugin defaults
 
 Set plugin-wide defaults in `~/.openclaw/openclaw.json`:
 
@@ -225,6 +225,8 @@ diff --git a/src/example.ts b/src/example.ts
 
 ## Notes
 
+- Multi-file patches start with a changed-files summary card: totals, per-file `+N`/`-N` stats, change badges, and anchor links.
+- Rendered PNG/PDF files keep the per-file header counts but omit the interactive view toggles.
 - The viewer is hosted locally through the gateway under `/plugins/diffs/...`.
 - Artifacts are ephemeral and stored in the plugin temp subfolder (`$TMPDIR/openclaw-diffs`).
 - Default viewer URLs use loopback (`127.0.0.1`) unless you set plugin `viewerBaseUrl`, pass `baseUrl`, or use `gateway.bind=custom` + `gateway.customBindHost`.
 
@@ -40,6 +40,9 @@ describe("renderDiffDocument", () => {
     expect(rendered.html).toContain("--diffs-line-height: 24px;");
     expect(rendered.html).toContain("--diffs-font-size: 15px;");
     expect(rendered.html).not.toContain("fonts.googleapis.com");
+    expect(rendered.html).not.toContain('<nav class="oc-diff-card oc-diff-nav"');
+    expect(rendered.html).toContain("@media (prefers-reduced-motion: reduce)");
+    expect(rendered.html).toContain("scroll-behavior: auto;");
   });
 
   it("normalizes non-finite presentation numbers before rendering CSS", async () => {
@@ -173,14 +176,16 @@ describe("renderDiffDocument", () => {
     expect(payload.langs).toEqual(["abap"]);
   });
 
-  it("renders multi-file patch input", async () => {
+  it("renders multi-file patch input with a changed-files summary nav", async () => {
     const patch = [
       "diff --git a/a.ts b/a.ts",
       "--- a/a.ts",
       "+++ b/a.ts",
-      "@@ -1 +1 @@",
+      "@@ -1,2 +1,3 @@",
       "-const a = 1;",
       "+const a = 2;",
+      "+const extra = true;",
+      " const keep = 0;",
       "diff --git a/b.ts b/b.ts",
       "--- a/b.ts",
       "+++ b/b.ts",
@@ -214,6 +219,101 @@ describe("renderDiffDocument", () => {
     expect(rendered.fileCount).toBe(2);
     expect(rendered.html).toContain("Workspace patch");
     expect(rendered.imageHtml).toContain("max-width: 1180px;");
+
+    const html = rendered.html ?? "";
+    expect(html).toContain('<nav class="oc-diff-card oc-diff-nav" aria-label="Changed files">');
+    expect(html).toContain("2 changed files");
+    expect(html).toContain(
+      '<span class="oc-diff-nav-additions">+3</span><span class="oc-diff-nav-deletions">-2</span>',
+    );
+    expect(html).toContain(
+      '<span class="oc-diff-nav-additions">+2</span><span class="oc-diff-nav-deletions">-1</span>',
+    );
+    expect(html).toContain('href="#oc-diff-file-1"');
+    expect(html).toContain('id="oc-diff-file-1"');
+    expect(html).toContain('href="#oc-diff-file-2"');
+    expect(html).toContain('id="oc-diff-file-2"');
+    expect(rendered.imageHtml).toContain('<nav class="oc-diff-card oc-diff-nav"');
+  });
+
+  it("labels added, deleted, and renamed files in the summary nav and escapes names", async () => {
+    const patch = [
+      "diff --git a/new.ts b/new.ts",
+      "new file mode 100644",
+      "--- /dev/null",
+      "+++ b/new.ts",
+      "@@ -0,0 +1 @@",
+      "+const created = true;",
+      "diff --git a/old.ts b/old.ts",
+      "deleted file mode 100644",
+      "--- a/old.ts",
+      "+++ /dev/null",
+      "@@ -1 +0,0 @@",
+      "-const removed = true;",
+      "diff --git a/before.ts b/after.ts",
+      "similarity index 90%",
+      "rename from before.ts",
+      "rename to after.ts",
+      "--- a/before.ts",
+      "+++ b/after.ts",
+      "@@ -1 +1 @@",
+      "-const v = 1;",
+      "+const v = 2;",
+      "diff --git a/a&b.ts b/a&b.ts",
+      "--- a/a&b.ts",
+      "+++ b/a&b.ts",
+      "@@ -1 +1 @@",
+      "-x",
+      "+y",
+    ].join("\n");
+
+    const rendered = await renderDiffDocument(
+      {
+        kind: "patch",
+        patch,
+      },
+      {
+        presentation: DEFAULT_DIFFS_TOOL_DEFAULTS,
+        image: resolveDiffImageRenderOptions({ defaults: DEFAULT_DIFFS_TOOL_DEFAULTS }),
+        expandUnchanged: false,
+      },
+      "viewer",
+    );
+
+    const html = rendered.html ?? "";
+    expect(html).toContain("4 changed files");
+    expect(html).toContain('<span class="oc-diff-nav-badge" data-change="added">added</span>');
+    expect(html).toContain('<span class="oc-diff-nav-badge" data-change="deleted">deleted</span>');
+    expect(html).toContain('<span class="oc-diff-nav-badge" data-change="renamed">renamed</span>');
+    expect(html).toContain("before.ts &rarr; after.ts");
+    expect(html).toContain("a&amp;b.ts");
+  });
+
+  it("omits the summary nav for single-file patches", async () => {
+    const patch = [
+      "diff --git a/solo.ts b/solo.ts",
+      "--- a/solo.ts",
+      "+++ b/solo.ts",
+      "@@ -1 +1 @@",
+      "-const solo = 1;",
+      "+const solo = 2;",
+    ].join("\n");
+
+    const rendered = await renderDiffDocument(
+      {
+        kind: "patch",
+        patch,
+      },
+      {
+        presentation: DEFAULT_DIFFS_TOOL_DEFAULTS,
+        image: resolveDiffImageRenderOptions({ defaults: DEFAULT_DIFFS_TOOL_DEFAULTS }),
+        expandUnchanged: false,
+      },
+      "viewer",
+    );
+
+    expect(rendered.fileCount).toBe(1);
+    expect(rendered.html).not.toContain('<nav class="oc-diff-card oc-diff-nav"');
   });
 
   it("rejects patches that exceed file-count limits", async () => {