diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index a726b2af4..afe5a8e1e 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -115,6 +115,7 @@ jobs:
           packages/ui/utils/diagramAnchorGraphviz.test.ts
           packages/ui/hooks/useAnnotationHighlighter.diagramSkip.test.tsx
           packages/ui/components/Viewer.diagramLazyRestore.test.tsx
+          packages/ui/components/Viewer.diagramAnchorHostile.test.tsx
           packages/ui/components/CommentPopover.skillReferences.test.tsx
           packages/ui/components/SkillReferenceMenu.placement.test.tsx
           packages/ui/components/sidebar/FileBrowser.test.ts
diff --git a/AGENTS.md b/AGENTS.md
index a5526d782..06af20e5c 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -600,7 +600,7 @@ During normal plan review, an Archive sidebar tab provides the same browsing via
 | `/api/external-annotations/stream` | GET | SSE stream for real-time external annotations |
 | `/api/external-annotations` | GET | Snapshot of external annotations (polling fallback, `?since=N` for version gating) |
 | `/api/external-annotations` | POST | Add external annotations (single or batch `{ annotations: [...] }`) |
-| `/api/external-annotations` | PATCH | Update fields on a single annotation (`?id=`) |
+| `/api/external-annotations` | PATCH | Update fields on a single annotation (`?id=`). The body is allowlisted and field-validated by `validateAnnotationPatch` (`@plannotator/core/external-annotation`, both runtimes) with the SAME validators POST applies — `diagramAnchor` / `htmlAnchor` / `elementContext` / the target arrays through their own fail-closed parsers, `inReplyTo` through `validateReplyTarget`, the scalars by type and cap. A bad value is `400`, unknown keys are dropped, `id` and `source` stay immutable, and `null` clears an optional field but is refused on an anchor or a structural one |
 | `/api/external-annotations` | DELETE | Remove by `?id=`, `?source=`, or clear all |
 
 ### Review Server (`packages/server/review.ts`)
@@ -634,7 +634,7 @@ During normal plan review, an Archive sidebar tab provides the same browsing via
 | `/api/external-annotations/stream` | GET | SSE stream for real-time external annotations |
 | `/api/external-annotations` | GET | Snapshot of external annotations (polling fallback, `?since=N` for version gating) |
 | `/api/external-annotations` | POST | Add external annotations (single or batch `{ annotations: [...] }`) |
-| `/api/external-annotations` | PATCH | Update fields on a single annotation (`?id=`) |
+| `/api/external-annotations` | PATCH | Update fields on a single annotation (`?id=`). The body is allowlisted and field-validated by `validateAnnotationPatch` (`@plannotator/core/external-annotation`, both runtimes) with the SAME validators POST applies — `diagramAnchor` / `htmlAnchor` / `elementContext` / the target arrays through their own fail-closed parsers, `inReplyTo` through `validateReplyTarget`, the scalars by type and cap. A bad value is `400`, unknown keys are dropped, `id` and `source` stay immutable, and `null` clears an optional field but is refused on an anchor or a structural one |
 | `/api/external-annotations` | DELETE | Remove by `?id=`, `?source=`, or clear all |
 | `/api/agents/capabilities` | GET | Check available agent providers (claude, codex, tour, guide, cursor, opencode, pi, copilot) |
 | `/api/agents/review-profiles` | GET | List launchable review profiles (enabled skills + builtin default) |
@@ -696,7 +696,7 @@ During normal plan review, an Archive sidebar tab provides the same browsing via
 | `/api/external-annotations/stream` | GET | SSE stream for real-time external annotations |
 | `/api/external-annotations` | GET | Snapshot of external annotations (polling fallback, `?since=N` for version gating) |
 | `/api/external-annotations` | POST | Add external annotations (single or batch `{ annotations: [...] }`) |
-| `/api/external-annotations` | PATCH | Update fields on a single annotation (`?id=`) |
+| `/api/external-annotations` | PATCH | Update fields on a single annotation (`?id=`). The body is allowlisted and field-validated by `validateAnnotationPatch` (`@plannotator/core/external-annotation`, both runtimes) with the SAME validators POST applies — `diagramAnchor` / `htmlAnchor` / `elementContext` / the target arrays through their own fail-closed parsers, `inReplyTo` through `validateReplyTarget`, the scalars by type and cap. A bad value is `400`, unknown keys are dropped, `id` and `source` stay immutable, and `null` clears an optional field but is refused on an anchor or a structural one |
 | `/api/external-annotations` | DELETE | Remove by `?id=`, `?source=`, or clear all |
 
 All servers use random ports locally or fixed port (`19432`) in remote mode.
@@ -966,7 +966,7 @@ Text highlighting uses `web-highlighter` library. Code blocks use manual `<mark>
 
 *Counts:* the panel header shows the scoped count, but the session total the decision control runs on (`feedbackAnnotationCount`) is computed from session state and is unaffected by the toggle — switching scope never changes what is submitted. Not covered: code review, single-document plan review, and live-app multi-page sessions (which already group their export by page). The compact/touch sheet reuses `AnnotationPanel`, so it gets the same toggle in its own header bar. Every panel prop is optional and additive, so a host that passes none of them (Workspaces) renders the previous panel, legacy affordance included.
 
-**Diagram comments (Mermaid and Graphviz fences).** A comment composed on a rendered diagram part — a click on a node, edge or cluster in the inline canvas or the popout — becomes an `Annotation` on the document with ONE additive field, `diagramAnchor` (`DiagramAnchor` from `@plannotator/core/diagram-anchor`, the `htmlAnchor` precedent): `{ v: 1, family, kind, id | from + to, label, sourceLine }` (families: flowchart, state, class, er, requirement, sequence, other, graphviz; kinds: node, edge, cluster, and `diagram` for the whole diagram, which has no id), where the anchor is the diagram's OWN id for the part (sequence parts carry classes, not ids, so the codec's ids are the actor's `name`, `msg-<n>`, `note-<n>`, `frame-<n>` by document order, restored with a label check because an ordinal moves) (never the rendered element id with its trailing counter, never geometry) and `sourceLine` names 1-based DOCUMENT lines (the fence's opening line is the offset, `Block.startLine`). The annotation carries the fence's `blockId`, `startOffset`/`endOffset` 0, the label as `originalText`, `type: COMMENT` and the tater identity, so it lists in the annotations rail beside text comments, exports, persists in drafts (opaque JSON), and restores after a reload: `useAnnotationHighlighter` skips rows carrying `diagramAnchor` (neither attempted nor unanchored), and `DiagramBlock` re-resolves them against every render through the engine's finder — id, then label, then unanchored — and reports through `Viewer.onRestoreReport` with its own comments as `attempted`, so App's `markdownUnanchoredIds` shows the same "Unanchored" chip a text comment gets. All three export paths (`exportAnnotations`, `exportLinkedDocAnnotations`, `exportAnnotationEntry`) print the location line `Diagram node <label> (<id>), line <n>` (whole diagram: `Diagram (<family>), lines a–b`) under the comment's heading; a WebMCP reply inherits its parent's `diagramAnchor`; the diagram block is `annotation-exclude`, so text restore can never wrap a `<mark>` inside the svg. The line comes from (`diagramAnchorLocationLine`; edges name both ends); the feedback archive records the validated anchor as `diagramAnchor`; `POST /api/external-annotations` accepts a validated `diagramAnchor` on plan comments (both runtimes, `400` when malformed; such rows carry `blockId: "external"`, and like a comment whose fence was deleted they are resolved BY ANCHOR against every diagram block through `DiagramAnchorClaims` (`components/diagram/anchorClaims`, provided by `Viewer`): the first block in document order whose finder resolves it shows it, and when every block answered and none did it is reported unanchored); share links drop the anchor exactly like `htmlAnchor` (`sharing.multiTarget.test.ts`). Selecting a diagram comment in the rail pulses its ring, pans it into view and scrolls the block into view. Plannotator passes `maxAdditionalTargets` 0 (one part per comment; the viewer's shift-click multi-select is a host opt-in) and no `onSave` (no Source pane; the in-block Show-source toggle keeps the fence readable). Read-only documents (archive) open no composer.
+**Diagram comments (Mermaid and Graphviz fences).** A comment composed on a rendered diagram part — a click on a node, edge or cluster in the inline canvas or the popout — becomes an `Annotation` on the document with ONE additive field, `diagramAnchor` (`DiagramAnchor` from `@plannotator/core/diagram-anchor`, the `htmlAnchor` precedent): `{ v: 1, family, kind, id | from + to, label, sourceLine }` (families: flowchart, state, class, er, requirement, sequence, other, graphviz; kinds: node, edge, cluster, and `diagram` for the whole diagram, which has no id), where the anchor is the diagram's OWN id for the part (sequence parts carry classes, not ids, so the codec's ids are the actor's `name`, `msg-<n>`, `note-<n>`, `frame-<n>` by document order, restored with a label check because an ordinal moves) (never the rendered element id with its trailing counter, never geometry) and `sourceLine` names 1-based DOCUMENT lines (the fence's opening line is the offset, `Block.startLine`). The annotation carries the fence's `blockId`, `startOffset`/`endOffset` 0, the label as `originalText`, `type: COMMENT` and the tater identity, so it lists in the annotations rail beside text comments, exports, persists in drafts (opaque JSON), and restores after a reload: `useAnnotationHighlighter` skips rows carrying `diagramAnchor` (neither attempted nor unanchored), and `DiagramBlock` re-resolves them against every render through the engine's finder — id, then label, then unanchored — and reports through `Viewer.onRestoreReport` with its own comments as `attempted`, so App's `markdownUnanchoredIds` shows the same "Unanchored" chip a text comment gets. All three export paths (`exportAnnotations`, `exportLinkedDocAnnotations`, `exportAnnotationEntry`) print the location line `Diagram node <label> (<id>), line <n>` (whole diagram: `Diagram (<family>), lines a–b`) under the comment's heading; a WebMCP reply inherits its parent's `diagramAnchor`; the diagram block is `annotation-exclude`, so text restore can never wrap a `<mark>` inside the svg. The line comes from (`diagramAnchorLocationLine`; edges name both ends); the feedback archive records the validated anchor as `diagramAnchor`; `POST /api/external-annotations` accepts a validated `diagramAnchor` on plan comments (both runtimes, `400` when malformed; such rows carry `blockId: "external"`, and like a comment whose fence was deleted they are resolved BY ANCHOR against every diagram block through `DiagramAnchorClaims` (`components/diagram/anchorClaims`, provided by `Viewer`): the first block in document order whose finder resolves it shows it, and when every block answered and none did it is reported unanchored); share links drop the anchor exactly like `htmlAnchor` (`sharing.multiTarget.test.ts`). Every renderer read of the field is nullish-safe (`ann.diagramAnchor != null`, `?.family`): a row reaches the renderer from several local ingests, and a malformed anchor must list as unanchored, never throw during render. Selecting a diagram comment in the rail pulses its ring, pans it into view and scrolls the block into view. Plannotator passes `maxAdditionalTargets` 0 (one part per comment; the viewer's shift-click multi-select is a host opt-in) and no `onSave` (no Source pane; the in-block Show-source toggle keeps the fence readable). Read-only documents (archive) open no composer.
 
 **Raw-HTML annotate:** the sandboxed viewer never mutates the visited page's DOM. Committed annotations render as numbered placed comment markers plus overlay-projected highlight rectangles inside a shadow-rooted fixed overlay host: the durable anchor data (element selector, text snapshot, normalized selected point) is persisted, and the markers/highlights are disposable projections re-resolved from it on every reconcile. Shift-click multi-select joins additional elements to one comment (`htmlAdditionalTargets`).
 
@@ -1093,6 +1093,31 @@ There is **one** highlighter in the app: the Shiki instance `@pierre/diffs` alre
 
 **Diagram theming (Mermaid):** diagrams follow the palette and mode the same way fences do, through ONE dynamic mapping rather than per-palette themes. `packages/ui/utils/mermaidTheme.ts` reads the live CSS tokens off the document element (`readThemeTokens`: `--background`, `--foreground`, `--card`, `--border`, `--muted`, `--muted-foreground`, `--primary`, the accent tokens, `--font-sans`), derives a complete Mermaid `themeVariables` set for every diagram family from them (`buildMermaidThemeVariables(tokens, mode)`, pure; base theme `dark` under a dark resolved mode, `default` under light; node fill from `card`, borders from `border`, edges and arrowheads from `muted-foreground`, text from `foreground`/`card-foreground`, clusters from `muted`, twelve categorical fills for pie/git/mindmap/journey seeded from `primary`, `accent`, `success`, `warning`, `destructive` and normalized to one lightness per page polarity), and `MermaidBlock` runs the global `mermaid.initialize` through `applyMermaidTheme` once per `(palette, mode)` key from `useTheme()` before each render, re-rendering mounted diagrams when the key changes. Every colour handed to Mermaid is opaque hex (its colour library does not read `oklch()`), and a contrast guard (`ensureContrast`) repairs any text-on-fill pair under WCAG 4.5:1 or line-on-canvas pair under 3:1 (plus 0.1 headroom) by the smallest OKLab step toward `foreground`, then `background`, then pure black/white — guarding page-level text and lines against every surface they can cross (the `bg-muted/30` canvas over the document card and over the bare page, `card`, `muted`, `popover`, ER rows), not the page background alone; `mermaidTheme.test.ts` sweeps every palette in `packages/ui/themes` in both modes against that rule, so a new palette cannot regress it. The pure toolkit behind it is `packages/ui/utils/cssColor.ts`. **Host fallback:** with no theme tokens on the document `readThemeTokens` returns `undefined` and the runtime keeps the static `MERMAID_CONFIG` (still `securityLevel: 'strict'`, pinned) with no extra `initialize`, so a host without `ThemeProvider`/`theme.css` renders exactly as before. Do not add per-palette Mermaid themes or per-theme `.mermaid` CSS — extend the token mapping instead. Graphviz has no theme system, so the renderer slot's `themeGraphvizSvg` recolors the DOT DEFAULTS onto the tokens after the scrub (the white page polygon removed, `fill="none"` → `var(--card)`, default black strokes → `var(--foreground)` on nodes and edges and `var(--border)` on clusters, `lightgrey` → `var(--muted)`, text → `var(--foreground)`) and leaves every author color alone; it needs no per-palette equivalent.
 
+**Printing (light half, one rule):** paper is white, so the whole page prints in
+the **LIGHT half of the user's pair** — prose, code and diagrams together.
+`ThemeProvider` forces `preferredMode` to `light` while printing
+(`packages/ui/hooks/usePrintMedia.ts`), which flows through the existing
+`applyThemeClasses` and, because `applyMermaidTheme` is keyed on
+`(palette, mode)`, re-renders every mounted diagram in the light palette;
+Graphviz follows with no re-render at all, since `themeGraphvizSvg` paints
+`var(--*)` tokens. Two signals drive it, because neither covers every path:
+`beforeprint` / `afterprint` (a real Cmd+P and print preview — the class write
+happens INSIDE the handler, since the print snapshot is taken before React
+would flush a state update) and a `matchMedia('print')` change (headless
+`page.emulateMedia({ media: 'print' })`, where the async diagram re-render also
+lands). The stored preference is never written, and a light-mode user sees no
+change. `usePrintMode` shares the subscription, so `.plannotator-print` is
+applied under print emulation too.
+
+`print.css` exempts diagram content from its typography rules with
+`:not([data-diagram-block] *)` on the blanket `body, div, span, p, …` selector
+and its `strong` / `em` / `p` siblings. A diagram colours itself and its own
+`<style>` carries no `!important`, so the blanket rule beat it: Mermaid 12
+draws node and edge labels as real HTML inside `<foreignObject>`
+(`span.nodeLabel > p`, `span.edgeLabel`), which is how a dark-palette flowchart
+used to print as empty boxes — near-black text on a near-black node fill. The
+zoom strip stays `data-print-hide`; rings and badges still print.
+
 **Bundle note:** Pierre imports Shiki's full bundle, so every grammar and theme is already inlined in the single-file builds; reusing its shared highlighter costs no extra bytes and needs no CDN or runtime wasm fetch. The Oniguruma WASM engine is dead weight under `shiki-js` and is aliased to `build/shiki-wasm-stub.ts` in the review, hook and portal Vite configs (via `resolve.alias`, which — unlike `plugins` — is shared with Vite's worker build).
 
 ## Requirements
diff --git a/apps/pi-extension/server/external-annotations.test.ts b/apps/pi-extension/server/external-annotations.test.ts
index e76a83fdd..98a342426 100644
--- a/apps/pi-extension/server/external-annotations.test.ts
+++ b/apps/pi-extension/server/external-annotations.test.ts
@@ -91,3 +91,120 @@ describe("pi external annotations: PATCH inReplyTo", () => {
 		expect((await patch(second, { text: "still fine" })).status).toBe(200);
 	});
 });
+
+/**
+ * Node mirror of the PATCH body-validation describe in
+ * packages/server/external-annotations.test.ts (#1560 follow-up): PATCH used
+ * to merge its body verbatim, so `{"diagramAnchor": null}` was answered 200
+ * and then blanked the page when the renderer read `.family` off it.
+ */
+describe("pi external annotations: PATCH body validation", () => {
+	const handler = createExternalAnnotationHandler("plan");
+	const reviewHandler = createExternalAnnotationHandler("review");
+	let server: Server;
+	let base = "";
+
+	beforeAll(async () => {
+		server = createServer(async (req, res) => {
+			const url = requestUrl(req);
+			const forReview = url.searchParams.get("mode") === "review";
+			const target = forReview ? reviewHandler : handler;
+			const handled = await target.handle(req, res, url);
+			if (!handled) {
+				res.writeHead(404);
+				res.end();
+			}
+		});
+		await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
+		const address = server.address();
+		if (!address || typeof address === "string") throw new Error("no port");
+		base = `http://127.0.0.1:${address.port}`;
+	});
+
+	afterAll(() => {
+		server.close();
+	});
+
+	const seed = (target: typeof handler, body: unknown) => {
+		const added = target.addAnnotations(body);
+		if ("error" in added) throw new Error(added.error);
+		return added.ids[0]!;
+	};
+
+	const patch = async (id: string, body: unknown, mode?: "review") => {
+		const qs = mode ? `&mode=${mode}` : "";
+		const res = await fetch(`${base}/api/external-annotations?id=${encodeURIComponent(id)}${qs}`, {
+			method: "PATCH",
+			headers: { "Content-Type": "application/json" },
+			body: JSON.stringify(body),
+		});
+		return {
+			status: res.status,
+			body: (await res.json()) as { error?: string; annotation?: Record<string, unknown> },
+		};
+	};
+
+	const VALID_ANCHOR = { v: 1, family: "flowchart", kind: "node", id: "D", label: "Approve?", sourceLine: [7, 7] };
+
+	test("refuses every malformed diagramAnchor and leaves the stored one intact", async () => {
+		const id = seed(handler, {
+			source: "linter",
+			type: "COMMENT",
+			text: "external finding",
+			originalText: "Approve?",
+			diagramAnchor: VALID_ANCHOR,
+		});
+
+		const nulled = await patch(id, { diagramAnchor: null });
+		expect(nulled.status).toBe(400);
+		expect(nulled.body.error).toContain("diagramAnchor");
+
+		for (const bad of [
+			"nope",
+			7,
+			{},
+			[],
+			{ ...VALID_ANCHOR, v: 2 },
+			{ ...VALID_ANCHOR, family: "not-a-family" },
+		]) {
+			expect((await patch(id, { diagramAnchor: bad })).status).toBe(400);
+		}
+
+		const snapshot = (await (await fetch(`${base}/api/external-annotations`)).json()) as {
+			annotations: Array<{ id: string; diagramAnchor?: unknown }>;
+		};
+		expect(snapshot.annotations.find((a) => a.id === id)?.diagramAnchor).toEqual(VALID_ANCHOR);
+	});
+
+	test("normalizes an accepted anchor and validates the other fields", async () => {
+		const id = seed(handler, { source: "linter", text: "note" });
+
+		const ok = await patch(id, { diagramAnchor: { ...VALID_ANCHOR, label: "x".repeat(600), stowaway: "dropped" } });
+		expect(ok.status).toBe(200);
+		const stored = ok.body.annotation?.diagramAnchor as Record<string, unknown>;
+		expect((stored.label as string).length).toBe(400);
+		expect(stored).not.toHaveProperty("stowaway");
+
+		expect((await patch(id, { diagramAnchor: { ...VALID_ANCHOR, sourceLine: [-3, -3] } })).status).toBe(200);
+		expect((await patch(id, { htmlAnchor: { tagName: "div" } })).status).toBe(400);
+		expect((await patch(id, { htmlAnchor: { selector: "#a", tagName: "div" } })).status).toBe(200);
+		expect((await patch(id, { elementContext: { id: "no-tag" } })).status).toBe(400);
+		expect((await patch(id, { images: [{ name: "a" }] })).status).toBe(400);
+		expect((await patch(id, { type: "NOT_A_TYPE" })).status).toBe(400);
+		expect((await patch(id, { text: 7 })).status).toBe(400);
+		expect((await patch(id, [{ text: "x" }])).status).toBe(400);
+
+		const dropped = await patch(id, { text: "edited", notAField: { deep: true } });
+		expect(dropped.status).toBe(200);
+		expect(dropped.body.annotation?.text).toBe("edited");
+		expect(dropped.body.annotation).not.toHaveProperty("notAField");
+	});
+
+	test("review mode keeps its own field set", async () => {
+		const id = seed(reviewHandler, { source: "linter", filePath: "a.ts", lineStart: 1, lineEnd: 1, text: "note" });
+		expect((await patch(id, { severity: "catastrophic" }, "review")).status).toBe(400);
+		expect((await patch(id, { severity: "nit" }, "review")).status).toBe(200);
+		expect((await patch(id, { decorations: ["explode"] }, "review")).status).toBe(400);
+		expect((await patch(id, { lineStart: "3" }, "review")).status).toBe(400);
+	});
+});
diff --git a/apps/pi-extension/server/external-annotations.ts b/apps/pi-extension/server/external-annotations.ts
index ef0eccdb8..bf4a49a31 100644
--- a/apps/pi-extension/server/external-annotations.ts
+++ b/apps/pi-extension/server/external-annotations.ts
@@ -15,6 +15,7 @@ import {
 	HEARTBEAT_COMMENT,
 	HEARTBEAT_INTERVAL_MS,
 	validateReplyTarget,
+	validateAnnotationPatch,
 	type StorableAnnotation,
 	type ExternalAnnotationEvent,
 } from "../generated/external-annotation.ts";
@@ -154,19 +155,28 @@ export function createExternalAnnotationHandler(mode: "plan" | "review") {
 					json(res, { error: "Invalid JSON" }, 400);
 					return true;
 				}
+				// Field-level validation with the same validators POST applies:
+				// unknown keys are dropped and a malformed structured value is a
+				// 400, never a stored one the renderer then reads a property off
+				// (`{"diagramAnchor": null}` used to blank the page).
+				// Mirrors packages/server/external-annotations.ts.
+				const patch = validateAnnotationPatch(mode, body);
+				if ("error" in patch) {
+					json(res, { error: patch.error }, 400);
+					return true;
+				}
 				// A reply must point at an existing, different annotation and must
 				// not close a cycle: the export and the panel treat cycle members as
 				// roots, but the invalid state should not be creatable in the first
 				// place. (POST never carries inReplyTo, so PATCH is the only ingest.)
-				// Mirrors packages/server/external-annotations.ts.
-				if (body && typeof body === "object" && "inReplyTo" in body) {
-					const problem = validateReplyTarget(store.getAll(), id, (body as { inReplyTo?: unknown }).inReplyTo);
+				if ("inReplyTo" in patch.fields) {
+					const problem = validateReplyTarget(store.getAll(), id, patch.fields.inReplyTo);
 					if (problem) {
 						json(res, { error: problem }, 400);
 						return true;
 					}
 				}
-				const updated = store.update(id, body as Partial<StorableAnnotation>);
+				const updated = store.update(id, patch.fields as Partial<StorableAnnotation>);
 				if (!updated) {
 					json(res, { error: "Not found" }, 404);
 					return true;
diff --git a/apps/pi-extension/vendor.sh b/apps/pi-extension/vendor.sh
index d1f31a780..33c5c6c9e 100755
--- a/apps/pi-extension/vendor.sh
+++ b/apps/pi-extension/vendor.sh
@@ -8,7 +8,7 @@ rm -rf generated
 mkdir -p generated generated/ai/providers
 
 # Modules that MOVED to @plannotator/core — vendor the real impl from core.
-for f in feedback-templates project favicon code-file annotatable annotation-threads diagram-anchor external-annotation agent-jobs agent-terminal source-save open-in-apps diff-paths diff-files guide guide-format guide-viewer-manifest compress crypto; do
+for f in feedback-templates project favicon code-file annotatable annotation-threads diagram-anchor html-anchor external-annotation agent-jobs agent-terminal source-save open-in-apps diff-paths diff-files guide guide-format guide-viewer-manifest compress crypto; do
   src="../../packages/core/$f.ts"
   printf '// @generated — DO NOT EDIT. Source: packages/core/%s.ts\n' "$f" | cat - "$src" > "generated/$f.ts"
 done
diff --git a/packages/core/external-annotation.ts b/packages/core/external-annotation.ts
index 5804bfe08..8344ca908 100644
--- a/packages/core/external-annotation.ts
+++ b/packages/core/external-annotation.ts
@@ -14,7 +14,17 @@
 // adapters import it from the module they already use.
 export { validateReplyTarget } from "./annotation-threads";
 
-import { parseDiagramAnchor, type DiagramAnchor } from "./diagram-anchor";
+import {
+  parseDiagramAdditionalTargets,
+  parseDiagramAnchor,
+  type DiagramAnchor,
+} from "./diagram-anchor";
+import {
+  MAX_PAGE_URL_LENGTH,
+  parseHtmlAdditionalTargets,
+  parseHtmlElementAnchor,
+  parseHtmlElementContext,
+} from "./html-anchor";
 
 // ---------------------------------------------------------------------------
 // Types
@@ -527,3 +537,247 @@ export function createAnnotationStore<T extends StorableAnnotation>(): Annotatio
     },
   };
 }
+
+// ---------------------------------------------------------------------------
+// PATCH validation (shared by both runtimes)
+// ---------------------------------------------------------------------------
+
+/**
+ * `PATCH /api/external-annotations?id=…` used to merge its body into the
+ * stored annotation verbatim: an unauthenticated localhost surface could
+ * write `{"diagramAnchor": null}` — a value POST refuses — and the renderer
+ * then read `.family` off it and took the page down (#1560 follow-up).
+ *
+ * The patch is now allowlisted and field-validated with the SAME validators
+ * POST applies: a structured field goes through its own fail-closed parser
+ * and a bad value is a 400, never a stored one. Unknown keys are dropped
+ * (the wire shape is additive, so an unknown key is a newer or foreign
+ * writer, not a reason to refuse the whole patch); `id` and `source` stay
+ * immutable — the store pins them too, this is the outer layer.
+ *
+ * Empty after filtering is fine: the PATCH is then a no-op that still
+ * answers 200 with the annotation, exactly as a patch of unknown keys did.
+ * `null` on an optional field keeps its established meaning — clear it — and
+ * is normalized to `undefined` so the stored row never holds a nullish value
+ * a consumer could read a property off; a required field refuses it.
+ */
+export type AnnotationPatchMode = "plan" | "review";
+
+type FieldValidator = (value: unknown) => { value: unknown } | ParseError;
+
+/** Cap mirrors the viewer's own diagram multi-select ceiling. */
+const MAX_DIAGRAM_ADDITIONAL_TARGETS = 16;
+const MAX_PATCH_IMAGES = 50;
+const MAX_PATCH_IMAGE_STRING = 4096;
+
+const ok = (value: unknown): { value: unknown } => ({ value });
+
+const str: FieldValidator = (value) =>
+  typeof value === "string" ? ok(value) : { error: "must be a string" };
+
+const bool: FieldValidator = (value) =>
+  typeof value === "boolean" ? ok(value) : { error: "must be a boolean" };
+
+const finiteNumber: FieldValidator = (value) =>
+  typeof value === "number" && Number.isFinite(value)
+    ? ok(value)
+    : { error: "must be a finite number" };
+
+const positiveInt: FieldValidator = (value) =>
+  typeof value === "number" && Number.isSafeInteger(value) && value > 0
+    ? ok(value)
+    : { error: "must be a positive integer" };
+
+const oneOf =
+  (values: readonly string[]): FieldValidator =>
+  (value) =>
+    typeof value === "string" && values.includes(value)
+      ? ok(value)
+      : { error: `must be one of: ${values.join(", ")}` };
+
+const cappedStr =
+  (max: number): FieldValidator =>
+  (value) =>
+    typeof value === "string" && value.length <= max
+      ? ok(value)
+      : { error: `must be a string of at most ${max} characters` };
+
+/** Attached images: `{ path, name }` pairs. */
+const imageList: FieldValidator = (value) => {
+  if (!Array.isArray(value)) return { error: "must be an array" };
+  if (value.length > MAX_PATCH_IMAGES) {
+    return { error: `must have at most ${MAX_PATCH_IMAGES} entries` };
+  }
+  const out: Array<{ path: string; name: string }> = [];
+  for (const entry of value) {
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+      return { error: "entries must be { path, name } objects" };
+    }
+    const { path, name } = entry as Record<string, unknown>;
+    if (typeof path !== "string" || path.length === 0 || path.length > MAX_PATCH_IMAGE_STRING) {
+      return { error: 'entries need a non-empty string "path"' };
+    }
+    if (typeof name !== "string" || name.length > MAX_PATCH_IMAGE_STRING) {
+      return { error: 'entries need a string "name"' };
+    }
+    out.push({ path, name });
+  }
+  return ok(out);
+};
+
+/** Parser-backed validators: the stored value is REPLACED by what the parser
+ *  returns, so a merged field is always one the renderer can read. */
+const viaParser =
+  <T>(parse: (value: unknown) => T | null | undefined, hint: string): FieldValidator =>
+  (value) => {
+    const parsed = parse(value);
+    if (parsed === null || parsed === undefined) return { error: hint };
+    return ok(parsed);
+  };
+
+/** Lenient array parsers (junk entries are dropped, never fatal) still
+ *  require an array: a scalar is a caller error worth reporting. */
+const viaArrayParser =
+  <T>(parse: (value: unknown) => T[]): FieldValidator =>
+  (value) =>
+    Array.isArray(value) ? ok(parse(value)) : { error: "must be an array" };
+
+const PLAN_PATCH_FIELDS: Record<string, FieldValidator> = {
+  type: oneOf(VALID_PLAN_TYPES),
+  text: str,
+  originalText: str,
+  author: str,
+  images: imageList,
+  isQuickLabel: bool,
+  quickLabelTip: str,
+  diffContext: oneOf(["added", "removed", "modified"]),
+  pageUrl: cappedStr(MAX_PAGE_URL_LENGTH),
+  prUrl: str,
+  inReplyTo: str,
+  blockId: str,
+  startOffset: finiteNumber,
+  endOffset: finiteNumber,
+  diagramAnchor: viaParser(
+    parseDiagramAnchor,
+    'expected { v: 1, family, kind, id | from + to, label, sourceLine }',
+  ),
+  diagramAdditionalTargets: viaArrayParser((value) =>
+    parseDiagramAdditionalTargets(value, MAX_DIAGRAM_ADDITIONAL_TARGETS),
+  ),
+  htmlAnchor: viaParser(
+    parseHtmlElementAnchor,
+    'expected { selector, tagName, text?, point? }',
+  ),
+  htmlAdditionalTargets: viaArrayParser((value) => parseHtmlAdditionalTargets(value)),
+  elementContext: viaParser(
+    parseHtmlElementContext,
+    'expected a bounded element description carrying a "tag"',
+  ),
+};
+
+const REVIEW_PATCH_FIELDS: Record<string, FieldValidator> = {
+  type: oneOf(VALID_REVIEW_TYPES),
+  scope: oneOf(VALID_SCOPES),
+  side: oneOf(VALID_SIDES),
+  filePath: str,
+  lineStart: finiteNumber,
+  lineEnd: finiteNumber,
+  charStart: finiteNumber,
+  charEnd: finiteNumber,
+  tokenText: str,
+  selectedText: str,
+  selectedTextFromEdits: bool,
+  text: str,
+  suggestedCode: str,
+  originalCode: str,
+  images: imageList,
+  author: str,
+  severity: oneOf(["important", "nit", "pre_existing"]),
+  reasoning: str,
+  reviewProfileLabel: str,
+  conventionalLabel: str,
+  decorations: (value) => {
+    if (!Array.isArray(value)) return { error: "must be an array" };
+    const allowed = ["blocking", "non-blocking", "if-minor"];
+    for (const entry of value) {
+      if (typeof entry !== "string" || !allowed.includes(entry)) {
+        return { error: `entries must be one of: ${allowed.join(", ")}` };
+      }
+    }
+    return ok([...value]);
+  },
+  inReplyTo: str,
+  prUrl: str,
+  prNumber: positiveInt,
+  prTitle: str,
+  prRepo: str,
+  diffScope: oneOf(["layer", "full-stack"]),
+  commitSha: str,
+  commitSubject: str,
+  gitButlerDiffType: str,
+  gitButlerDiffLabel: str,
+  gitButlerBase: str,
+  gitButlerSnapshotId: str,
+};
+
+/**
+ * Fields that carry the annotation's structure rather than its content: a
+ * PATCH may change them, never clear them. An annotation with no `type`, or a
+ * line comment with no `filePath`, is not a thing the UI can render — and the
+ * anchors are the crash vector this validator exists for, so `null` on one is
+ * the caller error it looks like (400), not a silent un-anchoring.
+ */
+const NON_CLEARABLE_FIELDS = new Set([
+  "type",
+  "originalText",
+  "blockId",
+  "startOffset",
+  "endOffset",
+  "scope",
+  "side",
+  "filePath",
+  "lineStart",
+  "lineEnd",
+  "diagramAnchor",
+  "diagramAdditionalTargets",
+  "htmlAnchor",
+  "htmlAdditionalTargets",
+  "elementContext",
+]);
+
+/**
+ * Validate and narrow a PATCH body for `mode`. Returns the fields that may be
+ * merged into the stored annotation, or a `ParseError` naming the field whose
+ * value failed its validator.
+ */
+export function validateAnnotationPatch(
+  mode: AnnotationPatchMode,
+  body: unknown,
+): { fields: Record<string, unknown> } | ParseError {
+  if (!body || typeof body !== "object" || Array.isArray(body)) {
+    return { error: "Request body must be a JSON object" };
+  }
+  const fieldsByName = mode === "plan" ? PLAN_PATCH_FIELDS : REVIEW_PATCH_FIELDS;
+  const fields: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(body as Record<string, unknown>)) {
+    // Identity fields are pinned (the store deletes them too).
+    if (key === "id" || key === "source" || key === "__proto__") continue;
+    const validator = fieldsByName[key];
+    // Unknown key: dropped, not fatal — the wire shape is additive.
+    if (!validator) continue;
+    // `undefined` never survives JSON, but a host calling the validator
+    // directly may pass it: treat it as "not provided".
+    if (value === undefined) continue;
+    if (value === null) {
+      if (NON_CLEARABLE_FIELDS.has(key)) {
+        return { error: `invalid "${key}": must not be null` };
+      }
+      fields[key] = undefined;
+      continue;
+    }
+    const result = validator(value);
+    if ("error" in result) return { error: `invalid "${key}": ${result.error}` };
+    fields[key] = result.value;
+  }
+  return { fields };
+}
diff --git a/packages/core/guide-viewer-manifest.ts b/packages/core/guide-viewer-manifest.ts
index 4742828d5..77dce66dc 100644
--- a/packages/core/guide-viewer-manifest.ts
+++ b/packages/core/guide-viewer-manifest.ts
@@ -5,10 +5,10 @@
 import type { GuideViewerAssets } from "./guide-format";
 
 export const GUIDE_VIEWER_MANIFEST: Omit<GuideViewerAssets, "baseUrl"> = {
-  js: "viewer.BnD4aEPi.js",
-  css: "viewer.rBaHmEce.css",
-  jsIntegrity: "sha384-LfSwy9OFdH7mo2/oM1ccvWbm2oqGV1CdiACxZvUgvbpw5UeUDnPJ6Gxf+FBTswDZ",
-  cssIntegrity: "sha384-MUYjuzvWVsshgfdFVhu23g5bvStgBgVsvEoCbBy/E/4r92db454BsDQQjs4fcu+F",
+  js: "viewer.CHc6x2n0.js",
+  css: "viewer.DilvVn0i.css",
+  jsIntegrity: "sha384-vVppc3Cfjf/9jt9zBzIFasRCLFfr0N+a45dr6KBjVTFhvdXkxnn2fQ88lIrXg2+w",
+  cssIntegrity: "sha384-EvOFwI14FdyDrbnpahJjjIRkQXWl7ihnmSB4mDmFdIJCrdKTB3KfEAN+wfMNT9fL",
   langs: {
     "astro": "chunks/astro.Ts5EKq2l.js",
     "c": "chunks/c.BIGW1oBm.js",
diff --git a/packages/server/external-annotations.test.ts b/packages/server/external-annotations.test.ts
index c26fcd86f..84d816d55 100644
--- a/packages/server/external-annotations.test.ts
+++ b/packages/server/external-annotations.test.ts
@@ -126,3 +126,153 @@ describe("PATCH /api/external-annotations", () => {
     expect((await patch(second, { text: "still fine" })).status).toBe(200);
   });
 });
+
+// ---------------------------------------------------------------------------
+// PATCH body validation (#1560 follow-up)
+// ---------------------------------------------------------------------------
+
+/**
+ * PATCH used to merge its body verbatim, so it could store values POST
+ * refuses. `{"diagramAnchor": null}` was answered 200 and then took the whole
+ * page down when the renderer read `.family` off it. Every field a PATCH can
+ * set now runs the validator POST runs.
+ */
+describe("PATCH /api/external-annotations: body validation", () => {
+  const seed = (handler: ReturnType<typeof createExternalAnnotationHandler>, body: unknown) => {
+    const added = handler.addAnnotations(body);
+    if ("error" in added) throw new Error(added.error);
+    return added.ids[0]!;
+  };
+
+  const patchWith = (handler: ReturnType<typeof createExternalAnnotationHandler>, id: string) =>
+    async (body: unknown) => {
+      const url = `http://localhost/api/external-annotations?id=${encodeURIComponent(id)}`;
+      const res = await handler.handle(
+        new Request(url, { method: "PATCH", headers: { "Content-Type": "application/json" }, body: JSON.stringify(body) }),
+        new URL(url),
+      );
+      return {
+        status: res!.status,
+        body: (await res!.json()) as { error?: string; annotation?: Record<string, unknown> },
+      };
+    };
+
+  const VALID_ANCHOR = { v: 1, family: "flowchart", kind: "node", id: "D", label: "Approve?", sourceLine: [7, 7] };
+
+  test("refuses every malformed diagramAnchor and never stores one", async () => {
+    const handler = createExternalAnnotationHandler("plan");
+    const id = seed(handler, {
+      source: "linter",
+      type: "COMMENT",
+      text: "external finding",
+      originalText: "Approve?",
+      diagramAnchor: VALID_ANCHOR,
+    });
+    const patch = patchWith(handler, id);
+
+    // The reported crash vector first: `null` answered 200 and blanked the page.
+    const nulled = await patch({ diagramAnchor: null });
+    expect(nulled.status).toBe(400);
+    expect(nulled.body.error).toContain("diagramAnchor");
+
+    for (const bad of [
+      "nope",
+      7,
+      {},
+      [],
+      { ...VALID_ANCHOR, v: 2 },
+      { ...VALID_ANCHOR, family: "not-a-family" },
+      { ...VALID_ANCHOR, kind: "node", id: undefined, from: undefined, to: undefined },
+    ]) {
+      const res = await patch({ diagramAnchor: bad });
+      expect(res.status).toBe(400);
+    }
+
+    // The stored anchor is untouched by every refused patch.
+    const url = "http://localhost/api/external-annotations";
+    const snapshot = (await (await handler.handle(new Request(url), new URL(url)))!.json()) as {
+      annotations: Array<{ id: string; diagramAnchor?: unknown }>;
+    };
+    expect(snapshot.annotations.find((a) => a.id === id)?.diagramAnchor).toEqual(VALID_ANCHOR);
+  });
+
+  test("accepts a valid diagramAnchor and normalizes it through the parser", async () => {
+    const handler = createExternalAnnotationHandler("plan");
+    const id = seed(handler, { source: "linter", text: "note" });
+    const patch = patchWith(handler, id);
+
+    const ok = await patch({ diagramAnchor: { ...VALID_ANCHOR, label: "x".repeat(600), stowaway: "dropped" } });
+    expect(ok.status).toBe(200);
+    const stored = ok.body.annotation?.diagramAnchor as Record<string, unknown>;
+    // Parser caps (400) and drops unknown keys — the same normalization POST applies.
+    expect((stored.label as string).length).toBe(400);
+    expect(stored).not.toHaveProperty("stowaway");
+
+    // An out-of-range source line drops to null while the target survives.
+    const negative = await patch({ diagramAnchor: { ...VALID_ANCHOR, sourceLine: [-3, -3] } });
+    expect(negative.status).toBe(200);
+    expect((negative.body.annotation?.diagramAnchor as { sourceLine: unknown }).sourceLine).toBeNull();
+  });
+
+  test("validates the other structured fields and the scalars", async () => {
+    const handler = createExternalAnnotationHandler("plan");
+    const id = seed(handler, { source: "linter", text: "note" });
+    const patch = patchWith(handler, id);
+
+    expect((await patch({ htmlAnchor: null })).status).toBe(400);
+    expect((await patch({ htmlAnchor: { tagName: "div" } })).status).toBe(400);
+    expect((await patch({ htmlAnchor: { selector: "#a", tagName: "div" } })).status).toBe(200);
+
+    expect((await patch({ elementContext: { id: "no-tag" } })).status).toBe(400);
+    expect((await patch({ elementContext: { tag: "BUTTON" } })).status).toBe(200);
+
+    expect((await patch({ images: "nope" })).status).toBe(400);
+    expect((await patch({ images: [{ name: "a" }] })).status).toBe(400);
+    expect((await patch({ images: [{ path: "/tmp/a.png", name: "a" }] })).status).toBe(200);
+
+    expect((await patch({ type: "NOT_A_TYPE" })).status).toBe(400);
+    expect((await patch({ type: "DELETION" })).status).toBe(200);
+    expect((await patch({ text: 7 })).status).toBe(400);
+    expect((await patch({ originalText: {} })).status).toBe(400);
+    expect((await patch({ pageUrl: "/a".padEnd(4000, "b") })).status).toBe(400);
+    expect((await patch({ pageUrl: "/settings?tab=2" })).status).toBe(200);
+  });
+
+  test("drops unknown keys instead of storing them, and keeps id immutable", async () => {
+    const handler = createExternalAnnotationHandler("plan");
+    const id = seed(handler, { source: "linter", text: "note" });
+    const patch = patchWith(handler, id);
+
+    const res = await patch({ text: "edited", notAField: { deep: true }, id: "hijacked" });
+    expect(res.status).toBe(200);
+    expect(res.body.annotation?.text).toBe("edited");
+    expect(res.body.annotation?.id).toBe(id);
+    expect(res.body.annotation).not.toHaveProperty("notAField");
+  });
+
+  test("refuses a non-object body", async () => {
+    const handler = createExternalAnnotationHandler("plan");
+    const id = seed(handler, { source: "linter", text: "note" });
+    const patch = patchWith(handler, id);
+    expect((await patch([{ text: "x" }])).status).toBe(400);
+    expect((await patch("text")).status).toBe(400);
+    expect((await patch(null)).status).toBe(400);
+  });
+
+  test("review mode keeps its own field set", async () => {
+    const handler = createExternalAnnotationHandler("review");
+    const id = seed(handler, { source: "linter", filePath: "a.ts", lineStart: 1, lineEnd: 1, text: "note" });
+    const patch = patchWith(handler, id);
+
+    expect((await patch({ severity: "catastrophic" })).status).toBe(400);
+    expect((await patch({ severity: "nit" })).status).toBe(200);
+    expect((await patch({ decorations: ["blocking"] })).status).toBe(200);
+    expect((await patch({ decorations: ["explode"] })).status).toBe(400);
+    expect((await patch({ suggestedCode: "const a = 1;" })).status).toBe(200);
+    expect((await patch({ lineStart: "3" })).status).toBe(400);
+    // A plan-only field is not a review field: dropped, not stored.
+    const dropped = await patch({ diagramAnchor: VALID_ANCHOR });
+    expect(dropped.status).toBe(200);
+    expect(dropped.body.annotation).not.toHaveProperty("diagramAnchor");
+  });
+});
diff --git a/packages/server/external-annotations.ts b/packages/server/external-annotations.ts
index 3cf2eb964..8093c1b0c 100644
--- a/packages/server/external-annotations.ts
+++ b/packages/server/external-annotations.ts
@@ -17,6 +17,7 @@ import {
   HEARTBEAT_COMMENT,
   HEARTBEAT_INTERVAL_MS,
   validateReplyTarget,
+  validateAnnotationPatch,
   type AnnotationStore,
   type StorableAnnotation,
   type ExternalAnnotationEvent,
@@ -176,15 +177,23 @@ export function createExternalAnnotationHandler(
         } catch {
           return Response.json({ error: "Invalid JSON" }, { status: 400 });
         }
+        // Field-level validation with the same validators POST applies:
+        // unknown keys are dropped and a malformed structured value is a 400,
+        // never a stored one that the renderer then reads a property off
+        // (`{"diagramAnchor": null}` used to blank the page).
+        const patch = validateAnnotationPatch(mode, body);
+        if ("error" in patch) {
+          return Response.json({ error: patch.error }, { status: 400 });
+        }
         // A reply must point at an existing, different annotation and must
         // not close a cycle: the export and the panel treat cycle members as
         // roots, but the invalid state should not be creatable in the first
         // place. (POST never carries inReplyTo, so PATCH is the only ingest.)
-        if (body && typeof body === "object" && "inReplyTo" in body) {
-          const problem = validateReplyTarget(store.getAll(), id, (body as { inReplyTo?: unknown }).inReplyTo);
+        if ("inReplyTo" in patch.fields) {
+          const problem = validateReplyTarget(store.getAll(), id, patch.fields.inReplyTo);
           if (problem) return Response.json({ error: problem }, { status: 400 });
         }
-        const updated = store.update(id, body as Partial<StorableAnnotation>);
+        const updated = store.update(id, patch.fields as Partial<StorableAnnotation>);
         if (!updated) {
           return Response.json({ error: "Not found" }, { status: 404 });
         }
diff --git a/packages/shared/code-nav.test.ts b/packages/shared/code-nav.test.ts
index 1c5a8b2d1..3b039b899 100644
--- a/packages/shared/code-nav.test.ts
+++ b/packages/shared/code-nav.test.ts
@@ -4,6 +4,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import {
   buildRgArgs,
+  isCodeNavPathAllowed,
   resolveCodeNav,
   buildSignature,
   classifyMatch,
@@ -988,18 +989,28 @@ describe("buildRgArgs directory exclusions (#1558)", () => {
     }
   });
 
-  test("a segment the origin file lives under is not excluded for that request", () => {
+  // The anchored glob only ever prunes the SEARCH ROOT, so an origin in a
+  // first-party `…/vendor/app/` package needs nothing lifted — and lifting it
+  // handed that request the real root `vendor/` tree back (#1559 follow-up).
+  test("a deep same-named package does not lift the root-only exclusion", () => {
     const args = buildRgArgs(
       "fetchContent",
       "java",
       "src/main/java/com/example/vendor/app/ExampleService.java",
     );
-    expect(args).not.toContain("!/vendor");
-    // Unrelated exclusions are untouched.
+    expect(args).toContain("!/vendor");
     expect(args).toContain("!node_modules");
     expect(args).toContain("!/target");
   });
 
+  test("an origin that really lives under the root directory lifts it", () => {
+    const args = buildRgArgs("fetchContent", "java", "vendor/third_party/Vendored.java");
+    expect(args).not.toContain("!/vendor");
+    // Only that one name: the other root-only exclusions stand.
+    expect(args).toContain("!/target");
+    expect(args).toContain("!node_modules");
+  });
+
   test("the origin-file rule also lifts an always-ignored segment", () => {
     const args = buildRgArgs("x", undefined, "packages/node_modules/dep/index.js");
     expect(args).not.toContain("!node_modules");
@@ -1056,6 +1067,8 @@ describeRg("resolveCodeNav against real ripgrep (#1558)", () => {
       `${root}/src/app/node_modules/dep/Dep.java`,
       javaSource("Dep"),
     );
+    // A neutral first-party file, the third of the QA repro's three.
+    await Bun.write(`${root}/src/other/Other.java`, javaSource("Other"));
   });
 
   afterAll(async () => {
@@ -1103,4 +1116,71 @@ describeRg("resolveCodeNav against real ripgrep (#1558)", () => {
     const found = paths(await resolve("src/app/node_modules/dep/Caller.java"));
     expect(found.some((p) => p.includes("node_modules/dep/Dep.java"))).toBe(true);
   });
+
+  // The QA repro (#1559 follow-up): three files define the same symbol — a
+  // first-party package whose path contains `vendor`, the repo-root `vendor/`
+  // tree, and a neutral file. From the package origin the ROOT match was
+  // returned, because the origin-file rule lifted the anchored glob.
+  test("a first-party `vendor` package does not un-exclude the root vendor tree", async () => {
+    const found = paths(await resolve("src/main/java/com/example/vendor/app/ExampleService.java"));
+    expect(found.some((p) => p.includes("com/example/vendor/app/ExampleService.java"))).toBe(true);
+    expect(found.some((p) => p.includes("src/other/"))).toBe(true);
+    expect(found.some((p) => p.includes("vendor/third_party/"))).toBe(false);
+  });
+
+  test("a file that really lives under root vendor/ still finds its own siblings", async () => {
+    const found = paths(await resolve("vendor/third_party/Caller.java"));
+    expect(found.some((p) => p.includes("vendor/third_party/Vendored.java"))).toBe(true);
+    // The exemption is that directory only: node_modules stays excluded.
+    expect(found.some((p) => p.includes("node_modules"))).toBe(false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Origin-file exemption is per directory INSTANCE (#1559 follow-up)
+// ---------------------------------------------------------------------------
+
+/**
+ * The exemption exists so a symbol in a changed file finds its own siblings
+ * even under a directory whose NAME looks like tool output. Lifting the glob
+ * lifted it tree-wide, so a request from a first-party `…/vendor/app/` package
+ * also returned the repo-root `vendor/` third-party tree. The rule is now: a
+ * match under an excluded directory is kept only when that same directory is
+ * an ancestor of the origin file.
+ */
+describe("isCodeNavPathAllowed", () => {
+  const DEEP_ORIGIN = "src/main/java/com/example/vendor/app/Widget.java";
+
+  test("the root-level excluded tree stays excluded for a deep same-named package", () => {
+    expect(isCodeNavPathAllowed("vendor/RootVendorFile.java", DEEP_ORIGIN)).toBe(false);
+    // …while the origin's own package is untouched (it was never pruned).
+    expect(isCodeNavPathAllowed("src/main/java/com/example/vendor/app/Other.java", DEEP_ORIGIN)).toBe(true);
+    expect(isCodeNavPathAllowed("src/other/Other.java", DEEP_ORIGIN)).toBe(true);
+  });
+
+  test("a file that really lives under the root directory keeps its siblings", () => {
+    const origin = "vendor/RootVendorFile.java";
+    expect(isCodeNavPathAllowed("vendor/Sibling.java", origin)).toBe(true);
+    expect(isCodeNavPathAllowed("vendor/nested/Deep.java", origin)).toBe(true);
+    // A DIFFERENT excluded root is still excluded for it.
+    expect(isCodeNavPathAllowed("dist/Built.java", origin)).toBe(false);
+  });
+
+  test("always-ignored names are per instance too", () => {
+    const origin = "packages/app/node_modules/dep/index.js";
+    expect(isCodeNavPathAllowed("packages/app/node_modules/dep/other.js", origin)).toBe(true);
+    expect(isCodeNavPathAllowed("packages/lib/node_modules/dep/index.js", origin)).toBe(false);
+    expect(isCodeNavPathAllowed("node_modules/dep/index.js", origin)).toBe(false);
+  });
+
+  test("with no origin, and for ordinary paths, the plain rules apply", () => {
+    expect(isCodeNavPathAllowed("vendor/x.java")).toBe(false);
+    expect(isCodeNavPathAllowed("src/x.java")).toBe(true);
+    // A nested `vendor/` is not root-level, so the anchored rule leaves it.
+    expect(isCodeNavPathAllowed("src/vendor/x.java")).toBe(true);
+    // A FILE named like an excluded directory is a file, not a directory.
+    expect(isCodeNavPathAllowed("src/vendor")).toBe(true);
+    expect(isCodeNavPathAllowed("./vendor/x.java")).toBe(false);
+    expect(isCodeNavPathAllowed("vendor\\x.java")).toBe(false);
+  });
 });
diff --git a/packages/shared/code-nav.ts b/packages/shared/code-nav.ts
index 53ce5c180..75c387169 100644
--- a/packages/shared/code-nav.ts
+++ b/packages/shared/code-nav.ts
@@ -283,7 +283,58 @@ function isTestFile(filePath: string): boolean {
 
 /** Path segments of a repo-relative file path, `/` and `\` alike. */
 function pathSegments(filePath: string): Set<string> {
-  return new Set(filePath.split(/[/\\]/).filter(Boolean));
+  return new Set(splitPath(filePath));
+}
+
+/** Ordered path segments, `/` and `\` alike, with `.` and empties dropped. */
+function splitPath(filePath: string): string[] {
+  return filePath.split(/[/\\]/).filter((segment) => segment && segment !== ".");
+}
+
+/**
+ * Is `matchPath` allowed for a request that came from `originFilePath`?
+ *
+ * The origin-file exemption (#1558) lifts a directory exclusion so a symbol in
+ * a changed file can always find its own siblings. Lifting the GLOB, though,
+ * lifts it for the whole tree: a request from
+ * `src/main/java/com/example/vendor/app/Widget.java` also started returning
+ * matches from the repo-ROOT `vendor/`, which is exactly the third-party tree
+ * the exclusion exists for (#1559 follow-up).
+ *
+ * So the exemption is narrowed to the directory INSTANCE the origin lives in:
+ * a match under an excluded directory is kept only when that same directory is
+ * an ancestor of the origin file. Root-only names are additionally only
+ * considered at the search root, which is where `--glob !/vendor` prunes.
+ */
+export function isCodeNavPathAllowed(
+  matchPath: string,
+  originFilePath?: string,
+): boolean {
+  const segments = splitPath(matchPath);
+  const origin = originFilePath ? splitPath(originFilePath) : [];
+  // Only directory segments can be excluded; the last segment is the file.
+  for (let i = 0; i < segments.length - 1; i++) {
+    const name = segments[i]!;
+    const excluded =
+      CODE_NAV_ALWAYS_IGNORED_DIRS.includes(name) ||
+      (i === 0 && CODE_NAV_ROOT_ONLY_IGNORED_DIRS.includes(name));
+    if (!excluded) continue;
+    if (!isAncestorOfOrigin(segments, origin, i)) return false;
+  }
+  return true;
+}
+
+/** Do `segments[0..i]` name the same directory the origin sits under? */
+function isAncestorOfOrigin(
+  segments: string[],
+  origin: string[],
+  i: number,
+): boolean {
+  if (origin.length <= i + 1) return false;
+  for (let j = 0; j <= i; j++) {
+    if (origin[j] !== segments[j]) return false;
+  }
+  return true;
 }
 
 export function buildRgArgs(
@@ -311,6 +362,12 @@ export function buildRgArgs(
   const originSegments = originFilePath
     ? pathSegments(originFilePath)
     : new Set<string>();
+  // Which directory the origin file sits at the TOP of, if any. A root-only
+  // glob prunes the search root alone, so only an origin that actually lives
+  // under that root directory needs the exclusion lifted — a first-party
+  // package deeper in the tree (`src/…/vendor/app/`) was never pruned by it,
+  // and lifting it for that request un-excluded the real `vendor/` (#1559).
+  const originRoot = originFilePath ? (splitPath(originFilePath)[0] ?? "") : "";
 
   for (const dir of CODE_NAV_ALWAYS_IGNORED_DIRS) {
     if (originSegments.has(dir)) continue;
@@ -318,7 +375,7 @@ export function buildRgArgs(
   }
 
   for (const dir of CODE_NAV_ROOT_ONLY_IGNORED_DIRS) {
-    if (originSegments.has(dir)) continue;
+    if (originRoot === dir) continue;
     // Leading slash anchors the glob to the search root, so only a top-level
     // `vendor/` (etc.) is pruned — not a same-named package deeper in the tree.
     args.push("--glob", `!/${dir}`);
@@ -579,7 +636,7 @@ export async function resolveCodeNav(
     result.stdout,
     request.symbol,
     request.language,
-  );
+  ).filter((loc) => isCodeNavPathAllowed(loc.filePath, request.filePath));
 
   const ranked = rankLocations(locations, {
     sourceFilePath: request.filePath,
diff --git a/packages/ui/components/DiagramBlock.tsx b/packages/ui/components/DiagramBlock.tsx
index 828d2eacb..6bba8c642 100644
--- a/packages/ui/components/DiagramBlock.tsx
+++ b/packages/ui/components/DiagramBlock.tsx
@@ -134,19 +134,23 @@ export const DiagramBlock: React.FC<DiagramBlockProps & { kind: DiagramKind }> =
   const claims = sharedClaims ?? ownClaims;
   const claimsVersion = useSyncExternalStore(claims.subscribe, claims.getVersion, claims.getVersion);
 
+  // `diagramAnchor` is read defensively everywhere: a row can reach the
+  // renderer from any local ingest (the external-annotations API, a draft, a
+  // share link), so a nullish or malformed anchor must list as unanchored,
+  // never take the page down with a property read (`null.family`).
   const ownAnnotations = useMemo(
-    () => annotations.filter((ann) => ann.diagramAnchor !== undefined && ann.blockId === block.id),
+    () => annotations.filter((ann) => ann.diagramAnchor != null && ann.blockId === block.id),
     [annotations, block.id],
   );
   const unownedAnnotations = useMemo(
     () =>
       annotations.filter(
         (ann) =>
-          ann.diagramAnchor !== undefined &&
+          ann.diagramAnchor != null &&
           ann.blockId !== block.id &&
           !claims.blockIds.includes(ann.blockId) &&
           // A Graphviz anchor names a DOT part; it is never a Mermaid one.
-          (ann.diagramAnchor.family === 'graphviz') === (kind === 'graphviz'),
+          (ann.diagramAnchor?.family === 'graphviz') === (kind === 'graphviz'),
       ),
     [annotations, block.id, claims, kind],
   );
diff --git a/packages/ui/components/ThemeProvider.test.tsx b/packages/ui/components/ThemeProvider.test.tsx
index 43bf9c1c7..a352ddf84 100644
--- a/packages/ui/components/ThemeProvider.test.tsx
+++ b/packages/ui/components/ThemeProvider.test.tsx
@@ -97,43 +97,68 @@ function clickButton(target: HTMLButtonElement): void {
   target.dispatchEvent(new MouseEvent('click', { bubbles: true, cancelable: true }));
 }
 
+/**
+ * One MediaQueryList per media string, because the provider now asks for two
+ * of them (`(prefers-color-scheme: light)` and `print`) and a single shared
+ * stub would report the colour-scheme answer as the print answer.
+ */
 function installMatchMedia(initialMatches: boolean) {
-  let matches = initialMatches;
-  const listeners = new Set<(event: MediaQueryListEvent) => void>();
-  const media = '(prefers-color-scheme: light)';
-  const query = {
-    get matches() {
-      return matches;
-    },
-    media,
-    onchange: null,
-    addListener(listener: (event: MediaQueryListEvent) => void) {
-      listeners.add(listener);
-    },
-    removeListener(listener: (event: MediaQueryListEvent) => void) {
-      listeners.delete(listener);
-    },
-    addEventListener(_type: string, listener: EventListenerOrEventListenerObject) {
-      listeners.add(listener as (event: MediaQueryListEvent) => void);
-    },
-    removeEventListener(_type: string, listener: EventListenerOrEventListenerObject) {
-      listeners.delete(listener as (event: MediaQueryListEvent) => void);
-    },
-    dispatchEvent() {
-      return true;
-    },
-  } as MediaQueryList;
+  const state = new Map<string, boolean>([
+    ['(prefers-color-scheme: light)', initialMatches],
+    ['print', false],
+  ]);
+  const listeners = new Map<string, Set<(event: MediaQueryListEvent) => void>>();
+  const queries = new Map<string, MediaQueryList>();
+
+  function queryFor(media: string): MediaQueryList {
+    const existing = queries.get(media);
+    if (existing) return existing;
+    const own = new Set<(event: MediaQueryListEvent) => void>();
+    listeners.set(media, own);
+    const query = {
+      get matches() {
+        return state.get(media) ?? false;
+      },
+      media,
+      onchange: null,
+      addListener(listener: (event: MediaQueryListEvent) => void) {
+        own.add(listener);
+      },
+      removeListener(listener: (event: MediaQueryListEvent) => void) {
+        own.delete(listener);
+      },
+      addEventListener(_type: string, listener: EventListenerOrEventListenerObject) {
+        own.add(listener as (event: MediaQueryListEvent) => void);
+      },
+      removeEventListener(_type: string, listener: EventListenerOrEventListenerObject) {
+        own.delete(listener as (event: MediaQueryListEvent) => void);
+      },
+      dispatchEvent() {
+        return true;
+      },
+    } as MediaQueryList;
+    queries.set(media, query);
+    return query;
+  }
 
   Object.defineProperty(window, 'matchMedia', {
     configurable: true,
-    value: () => query,
+    value: (media: string) => queryFor(media),
   });
 
+  function emit(media: string, matches: boolean) {
+    state.set(media, matches);
+    const event = { matches, media } as MediaQueryListEvent;
+    for (const listener of listeners.get(media) ?? []) listener(event);
+  }
+
   return {
     setMatches(nextMatches: boolean) {
-      matches = nextMatches;
-      const event = { matches, media } as MediaQueryListEvent;
-      for (const listener of listeners) listener(event);
+      emit('(prefers-color-scheme: light)', nextMatches);
+    },
+    /** What `page.emulateMedia({ media: 'print' })` fires. */
+    setPrintMedia(printing: boolean) {
+      emit('print', printing);
     },
   };
 }
@@ -645,3 +670,130 @@ describe('ThemeProvider legacy setColorTheme', () => {
     expect(themeState().mode).toBe('dark');
   });
 });
+
+/**
+ * Printing renders the LIGHT half of the pair, on every surface at once.
+ *
+ * What regresses if these fail: a dark-palette page prints its own dark tokens
+ * under a print stylesheet that assumes white paper — which is how a Mermaid
+ * label (HTML inside `<foreignObject>`, so the stylesheet's near-black text
+ * applied to it) ended up near-black on a near-black node fill.
+ *
+ * `beforeprint` is asserted separately from the `print` media query because
+ * only the first runs before a real print snapshot, and only the second is
+ * what headless `emulateMedia({ media: 'print' })` fires.
+ */
+describe('ThemeProvider print mode', () => {
+  beforeEach(() => {
+    if (hasDom) {
+      originalMatchMediaDescriptor = Object.getOwnPropertyDescriptor(window, 'matchMedia');
+    }
+    stored = new Map<string, string>();
+    setStorageBackend({
+      getItem: key => stored.get(key) ?? null,
+      setItem: (key, value) => {
+        stored.set(key, value);
+      },
+      removeItem: key => {
+        stored.delete(key);
+      },
+    });
+  });
+
+  afterEach(async () => {
+    if (hasDom) {
+      await unmountTheme();
+      document.documentElement.className = '';
+      if (originalMatchMediaDescriptor) {
+        Object.defineProperty(window, 'matchMedia', originalMatchMediaDescriptor);
+      } else {
+        Reflect.deleteProperty(window, 'matchMedia');
+      }
+      originalMatchMediaDescriptor = undefined;
+    }
+    configStore.resetServerSync();
+    resetStorageBackend();
+  });
+
+  async function mountDarkPair(): Promise<void> {
+    stored.set('plannotator-theme', 'dark');
+    stored.set('plannotator-light-theme', 'one-light');
+    stored.set('plannotator-dark-theme', 'plannotator');
+    installMatchMedia(false);
+    await mountTheme();
+    expect(themeState().resolvedMode).toBe('dark');
+    expect(themeState().colorTheme).toBe('plannotator');
+  }
+
+  test.skipIf(!hasDom)('beforeprint flips to the light half and afterprint restores', async () => {
+    await mountDarkPair();
+
+    await act(async () => {
+      window.dispatchEvent(new Event('beforeprint'));
+    });
+    expect(themeState().resolvedMode).toBe('light');
+    expect(themeState().colorTheme).toBe('one-light');
+    expect(document.documentElement.classList.contains('light')).toBe(true);
+    expect(document.documentElement.classList.contains('theme-one-light')).toBe(true);
+    // The stored preference is untouched: this is a rendering override.
+    expect(themeState().mode).toBe('dark');
+    expect(themeState().darkTheme).toBe('plannotator');
+
+    await act(async () => {
+      window.dispatchEvent(new Event('afterprint'));
+    });
+    expect(themeState().resolvedMode).toBe('dark');
+    expect(themeState().colorTheme).toBe('plannotator');
+    expect(document.documentElement.classList.contains('light')).toBe(false);
+  });
+
+  test.skipIf(!hasDom)('the light tokens are on <html> before the print snapshot, not a tick later', async () => {
+    await mountDarkPair();
+
+    // Asserted INSIDE act, before it flushes: exactly what a real Cmd+P gives
+    // the handler — one synchronous event, then the snapshot. A React state
+    // flush would be too late, so the class write cannot depend on one.
+    await act(async () => {
+      window.dispatchEvent(new Event('beforeprint'));
+      expect(document.documentElement.classList.contains('light')).toBe(true);
+      expect(document.documentElement.classList.contains('theme-one-light')).toBe(true);
+    });
+
+    await act(async () => {
+      window.dispatchEvent(new Event('afterprint'));
+    });
+    expect(document.documentElement.classList.contains('light')).toBe(false);
+  });
+
+  test.skipIf(!hasDom)('the print media query drives it too (headless print emulation)', async () => {
+    stored.set('plannotator-theme', 'dark');
+    stored.set('plannotator-light-theme', 'one-light');
+    stored.set('plannotator-dark-theme', 'plannotator');
+    const media = installMatchMedia(false);
+    await mountTheme();
+    expect(themeState().resolvedMode).toBe('dark');
+
+    await act(async () => media.setPrintMedia(true));
+    expect(themeState().resolvedMode).toBe('light');
+    expect(themeState().colorTheme).toBe('one-light');
+
+    await act(async () => media.setPrintMedia(false));
+    expect(themeState().resolvedMode).toBe('dark');
+    expect(themeState().colorTheme).toBe('plannotator');
+  });
+
+  test.skipIf(!hasDom)('a light-mode user sees no change at all', async () => {
+    stored.set('plannotator-theme', 'light');
+    stored.set('plannotator-light-theme', 'one-light');
+    stored.set('plannotator-dark-theme', 'plannotator');
+    installMatchMedia(true);
+    await mountTheme();
+    const before = { ...themeState() };
+
+    await act(async () => {
+      window.dispatchEvent(new Event('beforeprint'));
+    });
+    expect(themeState().resolvedMode).toBe(before.resolvedMode);
+    expect(themeState().colorTheme).toBe(before.colorTheme);
+  });
+});
diff --git a/packages/ui/components/ThemeProvider.tsx b/packages/ui/components/ThemeProvider.tsx
index 090022dab..8b5a7eae6 100644
--- a/packages/ui/components/ThemeProvider.tsx
+++ b/packages/ui/components/ThemeProvider.tsx
@@ -17,6 +17,7 @@ import {
   type ThemePair,
 } from '../utils/themeRegistry';
 import type { Mode } from './themeModes';
+import { usePrintMedia } from '../hooks/usePrintMedia';
 
 // Kept here because published consumers already import Mode from ThemeProvider.
 export type { Mode } from './themeModes';
@@ -181,12 +182,37 @@ export function ThemeProvider({
 
   const [systemIsLight, setSystemIsLight] = useState(getSystemIsLight);
 
+  // Paper is white: printing renders the LIGHT half of the user's pair, on
+  // every surface at once. That is what the print stylesheet has always
+  // assumed (white ground, near-black text) and what a dark-palette page could
+  // not deliver on its own — a Mermaid label, drawn as HTML inside
+  // `<foreignObject>`, took the stylesheet's near-black text onto a near-black
+  // node fill and printed illegibly. Light-mode users see no change.
+  const printThemeRef = useRef<{ enter: () => void; exit: () => void }>({ enter: () => {}, exit: () => {} });
+  const printing = usePrintMedia({
+    // Applied from inside `beforeprint`, because the print snapshot is taken
+    // before React would flush the state update below. The re-render then
+    // applies the same classes, so the two can never disagree.
+    onEnter: () => printThemeRef.current.enter(),
+    onExit: () => printThemeRef.current.exit(),
+  });
+
   // Keep the OS-resolved preference separate from the half it selects.
-  const preferredMode: 'dark' | 'light' =
+  const screenPreferredMode: 'dark' | 'light' =
     mode === 'system' ? (systemIsLight ? 'light' : 'dark') : mode;
+  const preferredMode: 'dark' | 'light' = printing ? 'light' : screenPreferredMode;
   const colorTheme = resolvePairTheme(pair, preferredMode);
   const resolvedMode = resolveThemeMode(colorTheme, preferredMode);
 
+  const applyHalf = useCallback((half: ThemeHalf) => {
+    const theme = resolvePairTheme(configStore.get('themePair'), half);
+    applyThemeClasses(theme, resolveThemeMode(theme, half));
+  }, []);
+  printThemeRef.current = {
+    enter: () => applyHalf('light'),
+    exit: () => applyHalf(screenPreferredMode),
+  };
+
   // Read by the legacy setColorTheme, which must target the half on screen
   // without re-creating its callback on every mode change.
   const preferredModeRef = useRef(preferredMode);
diff --git a/packages/ui/components/Viewer.diagramAnchorHostile.test.tsx b/packages/ui/components/Viewer.diagramAnchorHostile.test.tsx
new file mode 100644
index 000000000..0baec87bb
--- /dev/null
+++ b/packages/ui/components/Viewer.diagramAnchorHostile.test.tsx
@@ -0,0 +1,184 @@
+/**
+ * A stored annotation whose `diagramAnchor` is not an anchor must never take
+ * the document down.
+ *
+ * `PATCH /api/external-annotations` merged its body verbatim, so any local
+ * process could store `{"diagramAnchor": null}` — a value POST refuses — and
+ * the diagram block then read `.family` off it: `TypeError: Cannot read
+ * properties of null`, thrown during render, the whole page blank. The server
+ * validator closes the hole; this is the second layer, because a row can also
+ * reach the renderer from a draft, a share link, or a future writer.
+ *
+ * What regresses if this fails: one malformed row blanks the page instead of
+ * listing as an ordinary comment.
+ *
+ * DOM-gated (DOM_TESTS=1).
+ */
+import { afterAll, afterEach, beforeAll, describe, expect, test } from 'bun:test';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import React, { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { installInertDiagramSvgParser } from '../test-setup/diagramSvg';
+import { AnnotationType, type Annotation } from '../types';
+import { parseMarkdownToBlocks } from '../utils/parser';
+
+const hasDom = typeof document !== 'undefined';
+
+// Viewer pulls in web-highlighter, whose UMD bundle reads `window` at
+// module-eval time; import lazily (same pattern as Viewer.diagramLazyRestore).
+const viewerMod = hasDom ? await import('./Viewer') : null;
+const Viewer = viewerMod?.Viewer as typeof import('./Viewer')['Viewer'];
+const panelMod = hasDom ? await import('./AnnotationPanel') : null;
+const AnnotationPanel = panelMod?.AnnotationPanel as typeof import('./AnnotationPanel')['AnnotationPanel'];
+const mermaidMod = hasDom ? await import('./MermaidBlock') : null;
+const setLoader = mermaidMod?.__setMermaidRuntimeLoaderForTests as
+  typeof import('./MermaidBlock')['__setMermaidRuntimeLoaderForTests'];
+
+const FIXTURES = join(import.meta.dir, '..', 'test-setup', 'fixtures', 'diagrams');
+const CAPTURE_ID = 'diagram-fixture';
+const SVG = readFileSync(join(FIXTURES, '06-flowchart-review-decision.svg'), 'utf8');
+const GEOMETRY = JSON.parse(readFileSync(join(FIXTURES, '06-flowchart-review-decision.geometry.json'), 'utf8')) as {
+  elements: Record<string, { bbox: { x: number; y: number; width: number; height: number }; ctm: DOMMatrix }>;
+};
+const CAPTURED = Object.entries(GEOMETRY.elements).map(([id, entry]) => [id.slice(CAPTURE_ID.length), entry] as const);
+
+const PROSE_AFTER = 'Some prose after the diagram.';
+const MARKDOWN = [
+  '# Plan',
+  '',
+  'Some prose before the diagram.',
+  '',
+  '```mermaid',
+  'flowchart LR',
+  '  U([Reviewer]) --> D{Approve?}',
+  '  D -->|Yes| M[(Merge)]',
+  '  D -->|No| R[Revise]',
+  '```',
+  '',
+  PROSE_AFTER,
+].join('\n');
+
+const BLOCKS = hasDom ? parseMarkdownToBlocks(MARKDOWN) : [];
+const FENCE_ID = hasDom ? (BLOCKS.find((b) => b.type === 'code')?.id ?? '') : '';
+
+const row = (id: string, diagramAnchor: unknown): Annotation =>
+  ({
+    id,
+    blockId: FENCE_ID,
+    startOffset: 0,
+    endOffset: 0,
+    type: AnnotationType.COMMENT,
+    text: 'external finding',
+    originalText: 'Approve?',
+    createdA: 1,
+    source: 'linter',
+    diagramAnchor,
+  }) as unknown as Annotation;
+
+/** Exactly the shapes an unvalidated PATCH could store. `null` is the one
+ *  that threw; the rest are inert today and must stay that way. */
+const HOSTILE: Annotation[] = [
+  row('h-null', null),
+  row('h-string', 'nope'),
+  row('h-number', 7),
+  row('h-empty-object', {}),
+  row('h-wrong-v', { v: 2, family: 'flowchart', kind: 'node', id: 'D', label: 'Approve?', sourceLine: [7, 7] }),
+  row('h-unknown-family', { v: 1, family: 'not-a-family', kind: 'node', id: 'D', label: 'Approve?', sourceLine: [7, 7] }),
+];
+
+let root: Root | null = null;
+let host: HTMLElement | null = null;
+let restoreParser: (() => void) | null = null;
+const svgProto = (hasDom ? ((globalThis as { SVGGraphicsElement?: typeof SVGElement }).SVGGraphicsElement ?? SVGElement).prototype : {}) as unknown as Record<string, unknown>;
+const elementProto = (hasDom ? Element.prototype : {}) as unknown as Record<string, unknown>;
+const saved = { getBBox: svgProto['getBBox'], getScreenCTM: svgProto['getScreenCTM'] };
+const noop = (): void => {};
+
+beforeAll(() => {
+  if (!hasDom) return;
+  restoreParser = installInertDiagramSvgParser();
+  elementProto['setPointerCapture'] ??= noop;
+  elementProto['releasePointerCapture'] ??= noop;
+  elementProto['hasPointerCapture'] ??= () => false;
+  svgProto['getBBox'] = function (this: Element) {
+    if (this.tagName.toLowerCase() === 'svg') return { x: 0, y: 0, width: 452, height: 182 };
+    const found = CAPTURED.find(([suffix]) => this.id.endsWith(suffix));
+    return found === undefined ? { x: 0, y: 0, width: 0, height: 0 } : { ...found[1].bbox };
+  };
+  svgProto['getScreenCTM'] = function (this: Element) {
+    if (this.tagName.toLowerCase() === 'svg') return { a: 1, b: 0, c: 0, d: 1, e: 0, f: 0 };
+    return CAPTURED.find(([suffix]) => this.id.endsWith(suffix))?.[1].ctm ?? null;
+  };
+  setLoader((async () => ({
+    initialize: noop,
+    render: (id: string) => Promise.resolve({ svg: SVG.replaceAll(CAPTURE_ID, id) }),
+  })) as never);
+});
+
+afterAll(() => {
+  if (!hasDom) return;
+  svgProto['getBBox'] = saved.getBBox;
+  svgProto['getScreenCTM'] = saved.getScreenCTM;
+  setLoader(undefined);
+  restoreParser?.();
+});
+
+afterEach(async () => {
+  if (root !== null) {
+    const finished = root;
+    await act(async () => { finished.unmount(); });
+    root = null;
+  }
+  host?.remove();
+  host = null;
+  if (hasDom) document.body.innerHTML = '';
+});
+
+async function settle(ms = 25): Promise<void> {
+  await act(async () => { await new Promise((resolve) => setTimeout(resolve, ms)); });
+}
+
+describe.if(hasDom)('Viewer: an annotation carrying a malformed diagramAnchor', () => {
+  test('renders the document and lists the row instead of throwing', async () => {
+    host = document.createElement('div');
+    document.body.appendChild(host);
+
+    await act(async () => {
+      root = createRoot(host!);
+      root.render(
+        <>
+          <Viewer
+            blocks={BLOCKS}
+            markdown={MARKDOWN}
+            annotations={HOSTILE}
+            onAddAnnotation={() => {}}
+            onSelectAnnotation={() => {}}
+            selectedAnnotationId={null}
+            mode="comment"
+            taterMode={false}
+            disableCodePathValidation
+          />
+          <AnnotationPanel
+            isOpen
+            annotations={HOSTILE}
+            blocks={BLOCKS}
+            selectedId={null}
+            onSelect={() => {}}
+            onDelete={() => {}}
+          />
+        </>,
+      );
+    });
+    await settle(80);
+
+    // The document is on screen — the crash blanked it entirely
+    // (`document.body.innerText.length === 0`, root with no children).
+    expect(host!.textContent).toContain(PROSE_AFTER);
+    expect(host!.querySelector('[data-diagram-block]')).not.toBeNull();
+    // Every hostile row is still readable in the panel.
+    for (const ann of HOSTILE) {
+      expect(host!.querySelector(`[data-annotation-panel] [data-annotation-id="${ann.id}"]`)).not.toBeNull();
+    }
+  });
+});
diff --git a/packages/ui/components/Viewer.tsx b/packages/ui/components/Viewer.tsx
index 211f98979..45c47c400 100644
--- a/packages/ui/components/Viewer.tsx
+++ b/packages/ui/components/Viewer.tsx
@@ -1071,7 +1071,10 @@ export const Viewer = forwardRef<ViewerHandle, ViewerProps>(({
   // it is unanchored, and the highlighter (which skips it) will not say so.
   useEffect(() => {
     if (diagramBlockKey !== '' || onRestoreReport === undefined) return;
-    const ids = annotations.filter((ann) => ann.diagramAnchor !== undefined).map((ann) => ann.id);
+    // `!= null`, not `!== undefined`: a nullish anchor is no anchor at all —
+    // the highlighter restores such a row by text, so it must not be counted
+    // here as a diagram comment nothing could resolve.
+    const ids = annotations.filter((ann) => ann.diagramAnchor != null).map((ann) => ann.id);
     if (ids.length > 0) onRestoreReport({ attempted: ids, unanchored: ids });
   }, [annotations, diagramBlockKey, onRestoreReport]);
 
diff --git a/packages/ui/hooks/usePrintMedia.ts b/packages/ui/hooks/usePrintMedia.ts
new file mode 100644
index 000000000..c7aabc0c9
--- /dev/null
+++ b/packages/ui/hooks/usePrintMedia.ts
@@ -0,0 +1,70 @@
+import { useEffect, useState } from 'react';
+
+/**
+ * "Is this document being rendered for paper right now?"
+ *
+ * Two signals, because neither one alone covers every path:
+ *
+ *  - `beforeprint` / `afterprint` — what a real Cmd+P and the browser's print
+ *    preview fire. Handlers run BEFORE the print snapshot, so a DOM or class
+ *    write made from one is in the printed output; a React state update
+ *    scheduled from one is not guaranteed to be.
+ *  - `matchMedia('print')` change — what headless print emulation
+ *    (`page.emulateMedia({ media: 'print' })`) and some preview
+ *    implementations fire instead; there the page keeps living in print media,
+ *    so async work (a diagram re-render) does land.
+ *
+ * Firefox may skip `afterprint` when a preview is dismissed, so a
+ * `visibilitychange` back to a visible document also exits print mode.
+ */
+export function subscribePrintMedia(setPrinting: (printing: boolean) => void): () => void {
+  if (typeof window === 'undefined') return () => {};
+
+  const onBeforePrint = () => setPrinting(true);
+  const onAfterPrint = () => setPrinting(false);
+  const onVisibilityChange = () => {
+    if (!document.hidden) setPrinting(false);
+  };
+
+  window.addEventListener('beforeprint', onBeforePrint);
+  window.addEventListener('afterprint', onAfterPrint);
+  document.addEventListener('visibilitychange', onVisibilityChange);
+
+  const query = typeof window.matchMedia === 'function' ? window.matchMedia('print') : null;
+  const onMediaChange = (event: MediaQueryListEvent) => setPrinting(event.matches);
+  query?.addEventListener?.('change', onMediaChange);
+  if (query?.matches) setPrinting(true);
+
+  return () => {
+    window.removeEventListener('beforeprint', onBeforePrint);
+    window.removeEventListener('afterprint', onAfterPrint);
+    document.removeEventListener('visibilitychange', onVisibilityChange);
+    query?.removeEventListener?.('change', onMediaChange);
+  };
+}
+
+/**
+ * React binding over `subscribePrintMedia`. `onEnter` / `onExit` run inside the
+ * event handler itself, which is the only place a change is guaranteed to
+ * reach a real print snapshot; the returned boolean is the ordinary (async)
+ * state for everything that can wait.
+ */
+export function usePrintMedia(callbacks?: { onEnter?: () => void; onExit?: () => void }): boolean {
+  const [printing, setPrinting] = useState(false);
+
+  useEffect(() => {
+    let active = false;
+    return subscribePrintMedia((next) => {
+      if (next === active) return;
+      active = next;
+      if (next) callbacks?.onEnter?.();
+      else callbacks?.onExit?.();
+      setPrinting(next);
+    });
+    // The callbacks are read through the closure on purpose: re-subscribing on
+    // every render would drop the listener mid-print.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  return printing;
+}
diff --git a/packages/ui/hooks/usePrintMode.ts b/packages/ui/hooks/usePrintMode.ts
index 4831b4e69..ed69a7d96 100644
--- a/packages/ui/hooks/usePrintMode.ts
+++ b/packages/ui/hooks/usePrintMode.ts
@@ -1,26 +1,22 @@
 import { useEffect } from 'react';
+import { subscribePrintMedia } from './usePrintMedia';
 
 /**
  * Manages print mode by toggling 'plannotator-print' class on <html>.
- * Includes visibilitychange fallback for Firefox, which may not fire
- * afterprint when print preview is closed without printing.
+ *
+ * Driven by `subscribePrintMedia`, so the class is applied for print media
+ * emulation (`page.emulateMedia({ media: 'print' })`, which fires no
+ * `beforeprint`) as well as for a real print, and is removed again on
+ * `afterprint` or on the visibility change Firefox leaves behind when a
+ * preview is dismissed without printing.
  */
 export function usePrintMode() {
   useEffect(() => {
-    const onBeforePrint = () => document.documentElement.classList.add('plannotator-print');
-    const onAfterPrint = () => document.documentElement.classList.remove('plannotator-print');
-    const onVisibilityChange = () => {
-      if (!document.hidden && document.documentElement.classList.contains('plannotator-print')) {
-        document.documentElement.classList.remove('plannotator-print');
-      }
-    };
-    window.addEventListener('beforeprint', onBeforePrint);
-    window.addEventListener('afterprint', onAfterPrint);
-    document.addEventListener('visibilitychange', onVisibilityChange);
+    const unsubscribe = subscribePrintMedia((printing) => {
+      document.documentElement.classList.toggle('plannotator-print', printing);
+    });
     return () => {
-      window.removeEventListener('beforeprint', onBeforePrint);
-      window.removeEventListener('afterprint', onAfterPrint);
-      document.removeEventListener('visibilitychange', onVisibilityChange);
+      unsubscribe();
       document.documentElement.classList.remove('plannotator-print');
     };
   }, []);
diff --git a/packages/ui/print.css b/packages/ui/print.css
index 05b514546..45cad0ce2 100644
--- a/packages/ui/print.css
+++ b/packages/ui/print.css
@@ -177,16 +177,39 @@
 
   /* ========== Typography ========== */
 
-  body, div, span, p, li, td, th, label, strong, em, b, i {
+  /*
+   * `:not([data-diagram-block] *)` keeps every typography rule off DIAGRAM
+   * content. Mermaid 12 draws node and edge labels as real HTML inside
+   * `<foreignObject>` (`span.nodeLabel > p`, `span.edgeLabel`), so a blanket
+   * `div, span, p { color: #1a1a1a !important }` repainted them — over a dark
+   * node fill that prints as an empty box. A diagram colours itself (and
+   * prints in the light half of the palette, see ThemeProvider), and its own
+   * `<style>` has no `!important` to defend itself with, so the exemption has
+   * to live here.
+   */
+  body,
+  div:not([data-diagram-block] *),
+  span:not([data-diagram-block] *),
+  p:not([data-diagram-block] *),
+  li:not([data-diagram-block] *),
+  td:not([data-diagram-block] *),
+  th:not([data-diagram-block] *),
+  label:not([data-diagram-block] *),
+  strong:not([data-diagram-block] *),
+  em:not([data-diagram-block] *),
+  b:not([data-diagram-block] *),
+  i:not([data-diagram-block] *) {
     color: #1a1a1a !important;
   }
 
-  strong, b {
+  strong:not([data-diagram-block] *),
+  b:not([data-diagram-block] *) {
     font-weight: bold !important;
     color: #000 !important;
   }
 
-  em, i {
+  em:not([data-diagram-block] *),
+  i:not([data-diagram-block] *) {
     font-style: italic !important;
     color: #1a1a1a !important;
   }
@@ -231,7 +254,7 @@
     color: #000 !important;
   }
 
-  p {
+  p:not([data-diagram-block] *) {
     margin: 0.5em 0;
     color: #1a1a1a !important;
   }