diff --git a/AGENTS.md b/AGENTS.md
index 06af20e5c..33b898208 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1091,7 +1091,7 @@ There is **one** highlighter in the app: the Shiki instance `@pierre/diffs` alre
 
 **Diagram engine (ui 0.41.0):** every Mermaid and Graphviz diagram renders through ONE renderer slot and ONE canvas, the viewer moved in from Workspaces (owner ruling: the new engine, not an option). `MermaidBlock` and `GraphvizBlock` are thin wrappers over `packages/ui/components/DiagramBlock.tsx`, which keeps the fence side (`diagramLanguages.ts`, the pending fence under "Rendering diagram…", the error panel with the source, the per-engine Retry epoch, the Show-source toggle, the natural-height box) and renders `DiagramViewer` (`packages/ui/components/diagram/`) inline and again at full size in `DiagramPopout` (the `TablePopout` chrome; one code path). The renderer slot is `packages/ui/utils/diagram-render.ts`: `renderDiagram(kind, renderId, source, theme)` loads the engine through its runtime slot (`utils/mermaid.ts` as before, with `applyMermaidTheme` per (palette, mode) before every render; `utils/graphviz.ts`, new, the same shape, `@viz-js/viz` pinned exactly `3.30.0`), sanitizes the output into a NODE (`sanitizeDiagramSvg` = DOMPurify `parseDiagramSvg` + the in-place `scrubDiagramSvg` belt: no script, no `on*`, no `javascript:`/`data:` reference, no `<a href>` — a Mermaid click binding must never turn a pinpoint click into a navigation), and pairs it with the engine's finder (`utils/diagram-anchor.ts` for Mermaid's id grammar, `utils/diagram-anchor-graphviz.ts` keyed on `g.node > title`, never `nodeN`). A load failure is a value (`runtimeUnavailable: true`), which is the one failure Retry can change; one automatic re-attempt runs after the slot's retry delay. The canvas (`DiagramCanvas`) mounts the node with `replaceChildren` inside a CSS-transformed wrapper — wheel/drag/`+`/`-`/`0`/arrow keys; click-to-select vs drag-to-pan on a pointer-type-aware threshold (4 px mouse, 10 px finger); NO hover targeting on a plain mouse-over (owner ruling: it read as messy and fought the pan hand — the ring under the pointer appears only while the platform modifier is held, `isModKeyHeld`, and disarms on its release, on any other key, and on blur); canvas keys ignore Meta/Ctrl/Alt so browser chords pass through; inline the canvas is `touch-action: pan-y` (a finger scrolls the page past it) and only the popout is `touch-none`; the zoom strip is `data-print-hide` while rings and badges print. Every edge gets an invisible 14 px hit path in ONE layer appended last in the svg root (`widenEdgeHitAreas`: bare geometry, ancestors' transforms composed, no id/class/`data-*`, `diagramHitSource` maps it back) — measured in Chromium, the only thing painted over an edge is its OWN label box, centred on its midpoint, so a label is a target that resolves to its edge, and because the hit layer sits over the nodes the canvas resolves a click by PRIORITY over `elementsFromPoint` (node, then edge, then cluster), never by `event.target`. A click that resolves no part comments on the WHOLE diagram (kind `diagram`), so a click never does nothing. The scrub also scopes every `<style>` to rules under the svg's own root id (`scopeDiagramCss`: no `@import`, no fetching `url(`, no rule that could restyle the page). And the overlay (`DiagramOverlay`) reprojects rings and badges from `getBBox` through `getScreenCTM` each frame (`utils/diagram-projection.ts`), so they keep constant pixel size at every zoom. `components/mermaidSvg.ts` is gone. Under happy-dom DOMPurify is not functional (foreign-realm fragment, mislabelled svg namespaces, a cached `Node.prototype.nodeName` getter), so DOM tests swap the parse step for an inert XML parse through `__setDiagramSvgParserForTests` (`packages/ui/test-setup/diagramSvg.ts`) while the scrub still runs; the DOMPurify parse is proven in Chromium (the parity run in the PR that landed it). Real rendered svgs for the codec tests live in `packages/ui/test-setup/fixtures/diagrams/` with Chromium-measured geometry beside them.
 
-**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.
+**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, shadow amount)` 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`. **Node shadow:** Mermaid 12's neo look shadows every node, cluster and actor from its own fixed `drop-shadow(1px 2px 2px rgba(185,185,185,1))` grey, which reads as a halo on a themed page. The look is kept and that one filter is replaced: `buildMermaidThemeVariables` sets `themeVariables.dropShadow` from `buildMermaidShadow(ground, amount)` at `DEFAULT_MERMAID_SHADOW_AMOUNT` (**0.7**, i.e. 70 on the user-facing 0-100 scale, where 100 reproduces Mermaid's own geometry exactly and 0 publishes `dropShadow: false` — plus `nodeShadow: false`, the only thing that reaches a state diagram's inline-filtered start/end dots — which the neo rules render as `filter: none`). The colour is derived from the palette's own ground and its POLARITY follows the page, the same way Mermaid's `insertLookDefs` picks a white flood colour on dark themes: on a dark page the ground lifted 82% toward white at alpha `0.18 + 0.72a`, on a light page darkened 40% toward black at `0.25 + 0.3a`, each asserted to differ from the ground in the direction that reads (white/black as the fallback, Mermaid's grey when the palette yields no usable ground). A black shadow on a near-black ground is a valid filter that paints nothing, which is why polarity — not just alpha — follows the page. The amount is the cookie-only `diagramShadow` setting (Settings → Display → "Diagram Shadow", steps 0/40/70/100, `packages/ui/utils/diagramShadow.ts`), which rides into the renderer as `DiagramTheme.shadowAmount` and into the cache key; at the default the key is byte-identical to the old `(palette, mode)` one. It is a paint-time filter only: fills and label colours are identical at every amount (pinned in `mermaidTheme.test.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 — that config carries the same 70 geometry with a fixed light shadow colour, since its own slate theme is dark. A host that wants Mermaid's grey back sets its own `themeVariables.dropShadow` after ours; one that wants no shadow passes `shadowAmount: 0`. 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.
diff --git a/bun.lock b/bun.lock
index 4654a0c34..a3d4b612f 100644
--- a/bun.lock
+++ b/bun.lock
@@ -290,7 +290,7 @@
     },
     "packages/ui": {
       "name": "@plannotator/ui",
-      "version": "0.41.1",
+      "version": "0.41.2",
       "dependencies": {
         "@base-ui/react": "^1.7.0",
         "@codemirror/autocomplete": "^6.20.3",
diff --git a/packages/core/guide-viewer-manifest.ts b/packages/core/guide-viewer-manifest.ts
index 77dce66dc..6ba6a9a7d 100644
--- a/packages/core/guide-viewer-manifest.ts
+++ b/packages/core/guide-viewer-manifest.ts
@@ -5,9 +5,9 @@
 import type { GuideViewerAssets } from "./guide-format";
 
 export const GUIDE_VIEWER_MANIFEST: Omit<GuideViewerAssets, "baseUrl"> = {
-  js: "viewer.CHc6x2n0.js",
+  js: "viewer.48O72WuZ.js",
   css: "viewer.DilvVn0i.css",
-  jsIntegrity: "sha384-vVppc3Cfjf/9jt9zBzIFasRCLFfr0N+a45dr6KBjVTFhvdXkxnn2fQ88lIrXg2+w",
+  jsIntegrity: "sha384-XQrIafIUrC1JvOSLEFyhqNObv7YmydTDPwXCDJvSV7UcU2BMouDtQADclC1uvAGK",
   cssIntegrity: "sha384-EvOFwI14FdyDrbnpahJjjIRkQXWl7ihnmSB4mDmFdIJCrdKTB3KfEAN+wfMNT9fL",
   langs: {
     "astro": "chunks/astro.Ts5EKq2l.js",
diff --git a/packages/ui/HANDOFF.md b/packages/ui/HANDOFF.md
index 23e897da0..c51f6f28c 100644
--- a/packages/ui/HANDOFF.md
+++ b/packages/ui/HANDOFF.md
@@ -219,7 +219,7 @@ We deliberately did **not** restructure the exports map in this PR (move-don't-r
 | `utils/mermaid-math-slot` | Alias target only: what a host redirects Mermaid's own `katex` import to, so `$$` labels in diagrams typeset through the math slot and the host build carries one KaTeX chunk. Never import it yourself. See "Lazy renderers and eager entries", item 2. |
 | `utils/identity-tater` | Side-effect entry that registers the full username dictionary into the identity generator slot. Import it only if you rely on the default tater names and want the full dictionary; a host with `identityProvider` should not. |
 | `utils/mermaid` (`loadMermaidRuntime`, `getMermaidRuntime`, `getMermaidRuntimeSource`, `setMermaidRuntime`, `MERMAID_CONFIG`) and `utils/mermaid-eager` | The Mermaid runtime slot and its eager registration. Omit `utils/mermaid-eager` for the lazy path with retry, which is what Plannotator itself does since 0.40.0 (Mermaid 12); import it to register the runtime in your entry chunk at startup. See "Lazy renderers and eager entries" and "Mermaid 12 (0.40.0)". |
-| `utils/mermaidTheme` (`buildMermaidThemeVariables`, `readThemeTokens`, `applyMermaidTheme`, `mermaidThemeKey`, `buildMermaidConfig`, `ensureContrast`) and `utils/cssColor` | Theme-aware diagram configuration: the pure token-to-`themeVariables` mapping with its contrast guard, the document token reader, and the cached per-`(palette, mode)` `initialize` step `MermaidBlock` runs before each render. Additive; with no theme tokens on the document the static `MERMAID_CONFIG` stays in force. See "Theme-aware Mermaid diagrams (0.40.0)". |
+| `utils/mermaidTheme` (`buildMermaidThemeVariables`, `readThemeTokens`, `applyMermaidTheme`, `mermaidThemeKey`, `buildMermaidConfig`, `ensureContrast`, `buildMermaidShadow`, `DEFAULT_MERMAID_SHADOW_AMOUNT`), `utils/diagramShadow` and `utils/cssColor` | Theme-aware diagram configuration: the pure token-to-`themeVariables` mapping with its contrast guard, the palette-derived node shadow (`options.shadowAmount`, default 0.7 of Mermaid's own), the document token reader, and the cached per-`(palette, mode, shadow amount)` `initialize` step `MermaidBlock` runs before each render. Additive; with no theme tokens on the document the static `MERMAID_CONFIG` stays in force. See "Theme-aware Mermaid diagrams (0.40.0)". |
 
 **AI is fully avoidable** — with one precision worth knowing. No AI *UI* is reachable from the supported components: `useAIChat` is imported only by `components/ai/DocumentAIChatPanel` and `useAIProviderConfig`, neither of which any supported component imports, and `CommentPopover`'s Ask-AI affordance exists only behind the optional `onAskAI` prop. `configure.ts` does statically import the `useAIChat` module (it needs `setAITransport`), but if you never use AI the hook is dead code and bundlers eliminate it — verified empirically: a standalone consumer's production bundle importing the full supported surface contains zero `/api/ai` strings. Don't import `components/ai/*` and don't pass `aiTransport`, and you ship no AI code.
 
@@ -689,6 +689,12 @@ Mermaid diagrams used to render from one static config in every palette and both
 
 **Fallback contract for hosts.** Nothing changes for a host that does not use the tokens: with no `--background`/`--foreground` on the document (no `ThemeProvider`, no `theme.css`), `readThemeTokens` returns `undefined`, `buildMermaidThemeVariables` returns `null`, `buildMermaidConfig(null)` is `MERMAID_CONFIG` itself, and `applyMermaidTheme` records the key without calling `initialize` at all, so the runtime keeps the static config the loader or the eager entry initialized it with and renders byte-identically to 0.39.0 (pinned by `utils/mermaidTheme.test.ts` and `components/MermaidBlock.theme.test.tsx`). Outside a `ThemeProvider`, `useTheme()` yields the default context (Plannotator dark), which only names the key. `MERMAID_CONFIG` keeps its value and meaning (`securityLevel: 'strict'` still pinned by `components/MermaidBlock.test.ts`; `flowchart.htmlLabels` and `curve` are carried into the dynamic config unchanged) and `loadMermaidRuntime` / the eager entry are untouched: the runtime is still initialized once at registration, and the theme apply is a second, cached `initialize` on top. A host that ships its own tokens under the same names gets themed diagrams for free; a host that wants the old slate look in a themed document can keep the tokens off the diagram's ancestors, since `readThemeTokens` reads the document element by default. New exports are additive; the only behaviour change is for documents that carry the tokens, where diagrams now follow them.
 
+**Node shadow (the one thing that is not a colour).** Mermaid 12's neo look paints a drop shadow on every node, cluster and actor, from its own fixed `drop-shadow(1px 2px 2px rgba(185,185,185,1))` — a grey that reads as a halo on a themed page and follows no palette. The look is kept and that one filter is replaced: `buildMermaidThemeVariables(tokens, mode, options?)` takes an optional **`options.shadowAmount`, 0..1, default `DEFAULT_MERMAID_SHADOW_AMOUNT` (0.7)**, and publishes `themeVariables.dropShadow` from the new pure `buildMermaidShadow(ground, amount)`; the returned `MermaidThemeSpec` carries the resolved `shadowAmount`. Geometry scales over a small floor — `x = 0.3 + 0.7a`, `y = blur = 0.6 + 1.4a` — so **1 reproduces Mermaid's `1px 2px 2px` exactly** and **0 publishes `dropShadow: false`** (plus `nodeShadow: false`, the only thing that reaches the inline `filter:url(#…-drop-shadow-small)` on a state diagram's small start/end dots), which the neo rules render as `filter: none`. The colour comes from the palette's own ground and its POLARITY follows the page, the same rule Mermaid's `insertLookDefs` uses (`floodColor = theme.includes('dark') ? '#FFFFFF' : '#000000'`): on a dark page the ground lifted 82% toward white at alpha `0.18 + 0.72a`, on a light page darkened 40% toward black at `0.25 + 0.3a`, each asserted to differ from the ground in the direction that reads (falling back to plain white or black; to Mermaid's own grey when the ground is not a usable colour at all). Polarity, not just alpha, is the point: a black shadow on a near-black ground is a valid filter that paints nothing.
+
+`mermaidThemeKey(colorTheme, mode, shadowAmount?)` takes the amount as a third argument and appends `#s<amount>` to the key **only when it is not the default**, so the cache key for a host that never names an amount is byte-identical to the `(palette, mode)` key of 0.40.0 and no extra `initialize` happens. `DiagramTheme` (`utils/diagram-render`) gains an optional `shadowAmount`, which `DiagramBlock` fills from Plannotator's cookie-only `diagramShadow` setting (Settings → Display → "Diagram Shadow": 0 / 40 / 70 / 100 on a 0-100 percent scale; `utils/diagramShadow` exports `DEFAULT_DIAGRAM_SHADOW`, `DIAGRAM_SHADOW_OPTIONS`, `isDiagramShadow` and `diagramShadowAmount`, and is deliberately import-free so the settings registry can read it without pulling the diagram mapping into every surface's module graph).
+
+**What a host does.** Nothing, to get the toned-down default. To keep **Mermaid's own grey**, pass your own `themeVariables.dropShadow` after ours (`{ ...buildMermaidConfig(spec), themeVariables: { ...spec.themeVariables, dropShadow: 'drop-shadow(1px 2px 2px rgba(185,185,185,1))' } }`) — or simply `buildMermaidThemeVariables(tokens, mode, { shadowAmount: 1 })` for the same geometry in your palette's own colour. To ship **no shadow**, pass `{ shadowAmount: 0 }`, or build the key with `mermaidThemeKey(palette, mode, 0)` if you drive `applyMermaidTheme` yourself. The static `MERMAID_CONFIG` a token-less host renders with carries the same 0.7 geometry with one fixed light colour (its own slate palette is dark) — that is the ONE byte that changed in the fallback config; `securityLevel: 'strict'`, `startOnLoad`, `flowchart.htmlLabels` and `curve` are untouched. The shadow is paint-time only: at every amount the fills and label colours the mapping produces are identical (pinned in `utils/mermaidTheme.test.ts`, which also sweeps every shipped palette in both modes for a default shadow in the readable direction).
+
 **Known limits.** `GraphvizBlock` already maps its output to `var(--foreground)` / `var(--muted-foreground)` / `var(--muted)` and needs nothing. Mermaid hardcodes a `#000000` stroke on the sequence `crosshead` marker (lost messages, `-x`), which no theme variable reaches; it stays as in every Mermaid theme. The Mermaid 12 upgrade shipped in the same 0.40.0 publish and reuses this mapping unchanged; the re-sweep on 12 is in "Mermaid 12 (0.40.0)".
 
 ## Element context through the host seam (0.40.0)
@@ -869,7 +875,8 @@ to fall back on:
 
 ## Publishing & versioning
 
-- **The current pair is `@plannotator/ui` `0.41.1` on `@plannotator/core` `0.25.4`.** Core is UNCHANGED from 0.41.0, so 0.41.1 publishes alone (`ui` only; core 0.25.4 must already be published). 0.41.1 is two fixes over 0.41.0 with no API change — the diagram engine is loaded lazily by the first diagram fence instead of riding every document read, and a press on the canvas's own controls no longer comments on the part behind them; see "0.41.1 — the engine is lazy, and the controls are not part of the diagram". The 0.41.0 notes below still describe the engine itself.
+- **The current pair is `@plannotator/ui` `0.41.2` on `@plannotator/core` `0.25.4`.** Core is UNCHANGED from 0.41.1, so 0.41.2 publishes alone (`ui` only; core 0.25.4 must already be published). 0.41.2 ships the palette-derived Mermaid node shadow at a default of 70% (`DEFAULT_MERMAID_SHADOW_AMOUNT`) and the Settings → Display "Diagram Shadow" control (0 / 40 / 70 / 100); see "Node shadow (the one thing that is not a colour)" under "Theme-aware Mermaid diagrams (0.40.0)" for the mapping — no API removal, only additive exports (`buildMermaidShadow`, `DEFAULT_MERMAID_SHADOW_AMOUNT`, `utils/diagramShadow`).
+- The pair 0.41.1 shipped as was `@plannotator/ui` `0.41.1` on `@plannotator/core` `0.25.4`. Core is UNCHANGED from 0.41.0, so 0.41.1 published alone (`ui` only; core 0.25.4 must already be published). 0.41.1 is two fixes over 0.41.0 with no API change — the diagram engine is loaded lazily by the first diagram fence instead of riding every document read, and a press on the canvas's own controls no longer comments on the part behind them; see "0.41.1 — the engine is lazy, and the controls are not part of the diagram". The 0.41.0 notes below still describe the engine itself.
 - **The pair 0.41.0 shipped as was `@plannotator/ui` `0.41.0` on `@plannotator/core` `0.25.4`. Publish `core` 0.25.4 first, then `ui` 0.41.0** (both by hand from `main` after merge; CI never publishes these packages). 0.41.0 is the diagram engine (see "Diagram engine (0.41.0)"): one renderer slot and one canvas behind `MermaidBlock` / `GraphvizBlock`, the `components/diagram` surface, the Graphviz runtime slot with `@viz-js/viz` pinned `3.30.0`, and `Annotation.diagramAnchor`; core 0.25.4 adds the `diagram-anchor` subpath ui imports, so a ui 0.41.0 on a published core 0.25.3 would fail to compile in a consumer.
 - The previous pair was `@plannotator/ui` `0.40.0` on `@plannotator/core` `0.25.3` (publish order the same). Three things shipped in 0.40.0: (1) **Mermaid 12.0.0**, pinned exactly (was `^11.17.2`): ELK layout by default for flowchart/state/class/ER/requirement, Safari 17.4+ / ES2024 floor, SVG ids byte-identical to 11 but `g.edgePaths` children now in declaration order, and the plan editor no longer imports `utils/mermaid-eager` (the lazy path is the default for everyone; hosts that want startup registration import the eager entry themselves) — see "Mermaid 12 (0.40.0)"; (2) **theme-aware Mermaid diagrams**: New additive exports `utils/mermaidTheme` (`buildMermaidThemeVariables`, `readThemeTokens`, `applyMermaidTheme`, `mermaidThemeKey`, `buildMermaidConfig`, `ensureContrast`, `isDarkBackground`, `MERMAID_THEME_TOKEN_NAMES`) and `utils/cssColor` (parser + OKLab/contrast toolkit). `MermaidBlock` now calls `useTheme()` and `applyMermaidTheme` before each render; `MERMAID_CONFIG`, `loadMermaidRuntime`, `mermaid-eager` and `securityLevel: 'strict'` are unchanged. A host whose document carries no theme tokens renders diagrams byte-identically to 0.39.0; a host that mounts `ThemeProvider` with `theme.css` gets diagrams in its palette and mode with no configuration. No new peer dependencies; core unchanged. See "Theme-aware Mermaid diagrams (0.40.0)".; (3) **element context through the host seam (#1521, #1549), which is what moves `core` to 0.25.3:** `@plannotator/core/html-anchor` gains `parseHtmlElementContext`, `MAX_ELEMENT_CONTEXT_BYTES` and `MAX_PAGE_URL_LENGTH`; `PersistedHtmlAnchor.elementContext?` and `HtmlAnnotationTarget.context?` now round-trip through `buildPersistedHtmlAnchor` and `projectHostThreads`. **Core changes here, so bump and publish `core` first** and update UI's exact core dependency before packing ui — a ui build that imports these from an older published core fails to compile in a consumer, the 0.38.0 failure mode. `@plannotator/ui/components/html-viewer` re-exports the validator, so 0.39.0's import site is unchanged, and rows without context stay byte-identical on the wire. `utils/parser` gains `includeOutline` on `elementContextExportBlock` / `exportAnnotationEntry`, and `exportAnnotationEntry`'s `includeRoute` now defaults to true per field. See "Element context through the host seam".
 - The previous pair was `@plannotator/ui` `0.39.0` on `@plannotator/core` `0.25.2` (core unchanged; nothing under `packages/core` moved). UI 0.39.0 adds **element context** to raw-HTML and live-app pinpoint annotations (#1517, #1520): a new optional `Annotation.elementContext` (`HtmlElementContext` in `@plannotator/ui/types`) and `HtmlAnnotationTarget.context`, captured by the bridge at click time (tag, id, author classes, ancestor `path`, `role`, accessible `name`, an allowlisted `attrs` set with href/src scrubbed of query and fragment, rendered `text`, an adaptive collapsed HTML `outline`, child count, viewport `rect`, nearest `landmark` and `heading`, a `component` hint, and in live-app sessions `page`), hard-capped at 2 KiB serialized per primary and 1 KiB per extra target, and re-validated at the parent trust boundary by the new `parseHtmlElementContext` export of `@plannotator/ui/components/html-viewer`. New helpers on `@plannotator/ui/utils/parser`: `elementContextExportBlock(ann, { includeRoute })` (the fenced skeleton plus selector/path/role/name/attrs/text/box/near lines the full export now prints under a context-bearing comment) and `exportAnnotationEntry(ann, { includeRoute })` (one annotation as a standalone feedback entry, a pure helper for hosts; `AnnotationPanel`'s card chrome is unchanged from 0.38.2). The field is purely descriptive: `HtmlElementAnchor` and restore are untouched, no `BRIDGE_PROTOCOL_VERSION` bump, share links drop it like anchors, annotations without it export byte-identically, and the repaint path posts only anchors to the bridge. **Host persistence gap in 0.39.0 itself, closed in the next publish (#1521, #1549)**: as shipped, 0.39.0's `@plannotator/core/html-anchor` (`buildPersistedHtmlAnchor`, `projectHostThreads`) does not carry `elementContext`, so a host pinned to 0.39.0 that persists through those helpers drops it on save and must persist and project the field itself. The next publish carries it end to end — see "Element context through the host seam". Peer ranges are unchanged from 0.38.2: `react` / `react-dom` `^19.2.3`, `tailwindcss` as before, and `@codemirror/state ^6.7.2` beside `@codemirror/view ^6.43.10`. Decision-control change in the same window (#1516): the header primary reads `Send Feedback` / `Post Comments` with no inline count (`DecisionPrimary.count` removed; internal, not host-supported surface).
diff --git a/packages/ui/README.md b/packages/ui/README.md
index 0eeca2832..b919f31aa 100644
--- a/packages/ui/README.md
+++ b/packages/ui/README.md
@@ -56,7 +56,7 @@ Building your own tooltip and removing the built-in double-click reset are host-
 The Mermaid runtime, the Graphviz engine, KaTeX and the username dictionary are off the static import graph of `Viewer`, so a host that bundles by route does not download them for a plain markdown read. Graphviz has its own slot since 0.41.0 (`utils/graphviz`, the same shape as Mermaid's: lazy `import('@viz-js/viz')` on the first dot fence, or `setGraphvizRuntime` from the host) and the block shows the source fence under a status until the SVG lands. Mermaid, Graphviz, KaTeX and the dictionary sit behind synchronous slots:
 
 - **Math.** Without registration, a math node renders its TeX as text in the same wrapper (same `data-math-tex` / `data-math-display` / `aria-label` / class names), loads KaTeX via `import('katex')`, and re-renders typeset. To keep math typeset on the very first commit, as Plannotator does, add one line to your entry: `import "@plannotator/ui/utils/math-eager";`. To put KaTeX and its stylesheet on one lazy chunk instead, pass `mathRendererLoader`. The stylesheet remains your job either way (see "Consuming it", step 3). The default `import('katex')` is the only runtime mention of `katex` in the package and lives in `utils/math-default-loader` (0.33.0), called only while no loader is registered; a registered loader is never backfilled by it, though a default load already in flight at registration still fills the slot (pre-existing), so register the loader before the first math render. Chunk emission is static, so a bundler still emits that chunk (never requested) unless you alias the module away; see HANDOFF.md "Lazy renderers and eager entries" for the two-line alias. The Mermaid runtime has its own `import("katex")` for `$$` labels, which leaves a second, shared KaTeX chunk in a host build even with the alias; since 0.34.0 a host redirects that one import (for importers inside the `mermaid` package only) to `@plannotator/ui/utils/mermaid-math-slot`, which typesets the labels through your registered renderer, so one KaTeX chunk remains and it is yours. Recipe and measurement in HANDOFF.md, same section. `resetMathRenderer()` empties the slot only and keeps a registered loader (0.34.0); `setMathRendererLoader(null)` is the explicit way back to the package default.
-- **Mermaid.** Without registration, the first diagram on a page fetches the runtime through `import('mermaid')` and the block shows the source fence under a "Rendering diagram" status until the SVG lands; a failed import is dropped from the memo, re-attempted once after a short delay, and the error panel (with the source) offers Retry, which issues another fresh attempt. **Since 0.40.0 (Mermaid 12.0.0, ELK layout by default, Safari 17.4+) this lazy path is Plannotator's own**: the plan editor no longer imports the eager entry, so a document with no diagram never downloads the runtime in a chunked build. `import "@plannotator/ui/utils/mermaid-eager";` in your entry registers and initializes the runtime at startup instead, if you would rather it never fail separately from the app. Mermaid 12 lays flowchart, state, class, ER and requirement diagrams out with ELK (orthogonal edges, different packing); every generated SVG `id` keeps its 11.x shape, but children of `g.edgePaths` are now in declaration order, so select edges by id (`{renderId}-L_{from}_{to}_{n}`, `{renderId}-edge{n}`), never by DOM position. Details in HANDOFF.md "Mermaid 12 (0.40.0)". **Diagrams follow the colour theme.** Before every render `MermaidBlock` calls `applyMermaidTheme` (`utils/mermaidTheme`), which reads the theme tokens off the document (`--background`, `--foreground`, `--card`, `--border`, `--muted`, `--muted-foreground`, `--primary`, the accent tokens and `--font-sans`; `readThemeTokens`), derives a complete `themeVariables` set for every diagram family from them (`buildMermaidThemeVariables(tokens, mode)`, pure; base theme `dark` under a dark resolved mode, `default` under light; every text-on-fill pair guarded to WCAG 4.5:1 and every line 3:1, rule in the module doc) and runs the global `mermaid.initialize` once per `(palette, mode)` key, re-rendering mounted diagrams when the key changes. The key comes from `useTheme()`, so a host that mounts `ThemeProvider` and ships `theme.css` gets diagrams in its palette with nothing to configure. **Fallback contract:** with no tokens on the document (no `ThemeProvider`, no `theme.css`) `readThemeTokens` returns `undefined`, nothing is re-initialized, and the runtime keeps the static `MERMAID_CONFIG` it was initialized with, so such a host renders byte-identically to 0.39.0. `MERMAID_CONFIG` keeps its value and meaning (`securityLevel: 'strict'` pinned); the new exports are additive. Honest limit of any in-page retry: a browser records a failed module fetch in its module map for the page lifetime, so a fresh `import()` of the same chunk URL rejects without a request; the retry recovers failures after the fetch (engine instantiation, initialize) and hosts that version chunk URLs. A host that needs recovery from a failed first fetch uses versioned chunk URLs or a `vite:preloadError` reload at app level.
+- **Mermaid.** Without registration, the first diagram on a page fetches the runtime through `import('mermaid')` and the block shows the source fence under a "Rendering diagram" status until the SVG lands; a failed import is dropped from the memo, re-attempted once after a short delay, and the error panel (with the source) offers Retry, which issues another fresh attempt. **Since 0.40.0 (Mermaid 12.0.0, ELK layout by default, Safari 17.4+) this lazy path is Plannotator's own**: the plan editor no longer imports the eager entry, so a document with no diagram never downloads the runtime in a chunked build. `import "@plannotator/ui/utils/mermaid-eager";` in your entry registers and initializes the runtime at startup instead, if you would rather it never fail separately from the app. Mermaid 12 lays flowchart, state, class, ER and requirement diagrams out with ELK (orthogonal edges, different packing); every generated SVG `id` keeps its 11.x shape, but children of `g.edgePaths` are now in declaration order, so select edges by id (`{renderId}-L_{from}_{to}_{n}`, `{renderId}-edge{n}`), never by DOM position. Details in HANDOFF.md "Mermaid 12 (0.40.0)". **Diagrams follow the colour theme.** Before every render `MermaidBlock` calls `applyMermaidTheme` (`utils/mermaidTheme`), which reads the theme tokens off the document (`--background`, `--foreground`, `--card`, `--border`, `--muted`, `--muted-foreground`, `--primary`, the accent tokens and `--font-sans`; `readThemeTokens`), derives a complete `themeVariables` set for every diagram family from them (`buildMermaidThemeVariables(tokens, mode)`, pure; base theme `dark` under a dark resolved mode, `default` under light; every text-on-fill pair guarded to WCAG 4.5:1 and every line 3:1, rule in the module doc) and runs the global `mermaid.initialize` once per `(palette, mode, shadow amount)` key, re-rendering mounted diagrams when the key changes. The key comes from `useTheme()`, so a host that mounts `ThemeProvider` and ships `theme.css` gets diagrams in its palette with nothing to configure. **The node shadow follows the palette too.** Mermaid 12's neo look shadows every node from a fixed `rgba(185,185,185,1)` grey; the mapping keeps the look and replaces that filter, setting `themeVariables.dropShadow` from the page's own ground at `options.shadowAmount` (0..1, default `DEFAULT_MERMAID_SHADOW_AMOUNT` = **0.7** of Mermaid's geometry; 1 reproduces its `1px 2px 2px` exactly, 0 publishes `dropShadow: false` and the neo rules render `filter: none`). Its polarity follows the page — lighter than the ground on a dark page, darker on a light one, which is what Mermaid's own `insertLookDefs` does and what keeps a shadow visible at all. A host that wants Mermaid's grey passes its own `themeVariables.dropShadow` after ours; one that wants none passes `{ shadowAmount: 0 }`. `mermaidThemeKey(palette, mode, amount?)` appends the amount only when it is not the default, so a host that names none keeps the key it had. **Fallback contract:** with no tokens on the document (no `ThemeProvider`, no `theme.css`) `readThemeTokens` returns `undefined`, nothing is re-initialized, and the runtime keeps the static `MERMAID_CONFIG` it was initialized with, so such a host renders byte-identically to 0.39.0. `MERMAID_CONFIG` keeps its value and meaning (`securityLevel: 'strict'` pinned); the new exports are additive. Honest limit of any in-page retry: a browser records a failed module fetch in its module map for the page lifetime, so a fresh `import()` of the same chunk URL rejects without a request; the retry recovers failures after the fetch (engine instantiation, initialize) and hosts that version chunk URLs. A host that needs recovery from a failed first fetch uses versioned chunk URLs or a `vite:preloadError` reload at app level.
 - **Identity.** With an `identityProvider` the generator is never called and the word lists stay out of your bundle. Without one, default names come from a small built-in pool of the same `adjective-noun-tater` shape; `import "@plannotator/ui/utils/identity-tater";` registers the full dictionary, or pass your own `identityGenerator`.
 
 Plannotator's own entries import the eager math and identity modules (`math-eager` and `identity-tater` in both `packages/editor/App.tsx` and `packages/review-editor/App.tsx`), which is what keeps math typeset on the first commit and names minted from the full dictionary; neither app imports `mermaid-eager` since 0.40.0, so the Mermaid runtime rides a lazy chunk on the share portal and is inlined by `inlineDynamicImports` in the single-file builds. `tests/entry-assets.test.ts` fails if an eager math/identity import is dropped or an eager Mermaid import creeps back. See HANDOFF.md "Lazy renderers and eager entries" and "Mermaid 12 (0.40.0)".
@@ -218,7 +218,7 @@ the in-flow host integration.
 
 ### Diagram engine (`components/diagram`; 0.41.0)
 
-One renderer slot and one canvas render every Mermaid and Graphviz diagram — the fences in `Viewer` (`MermaidBlock`, `GraphvizBlock`), their popout, and whatever a host renders itself. `DiagramViewer` from `@plannotator/ui/components/diagram` takes `kind`, `source`, `theme` (`{ colorTheme, mode }`), `comments: DiagramComment[]` and `onCreateComment(anchor, text, additionalTargets)`; pass `onSave(source) => Promise<{ status: 'ok' } | { status: 'stale', currentSource }>` to get the Source pane (left of the canvas on desktop, under it on the phone; `readOnlySource` shows it without Save), and `sourceOpen` to toggle it. Zoom, pan and fit are the canvas's (wheel, drag, `+` `-` `0`, arrow keys); a click opens the composer at the part beneath while a drag pans (4 px threshold, 10 px for a finger), nothing highlights on a plain mouse-over (the ring under the pointer needs the platform modifier held), every edge carries an invisible 14 px hit path in one top layer and a click is resolved by priority over everything under the pointer (node, then edge, then cluster; an edge label is its edge), a click on no part comments on the whole diagram (kind `diagram`), sequence diagrams are addressable (actors, messages, notes, frames), a saved comment paints a ring and a numbered badge from the array order, and every comment re-resolves against each render through the engine's finder (id, then label, then unanchored — reported through `onUnanchoredChange`). The anchor is `DiagramAnchor` from `@plannotator/core/diagram-anchor` (`{ v: 1, family, kind, id | from + to, label, sourceLine }`, document lines), and Plannotator stores it as `Annotation.diagramAnchor`. Runtime slots: `utils/mermaid` (as before) and `utils/graphviz` (new, same shape, `@viz-js/viz` pinned `3.30.0`), each lazy on first use or filled by the host. `DiagramPopout` is the full-size viewer in the `PopoutDialog` chrome. See HANDOFF.md § "Diagram engine (0.41.0)" for every export, the adapter, the sanitizer and the migration notes.
+One renderer slot and one canvas render every Mermaid and Graphviz diagram — the fences in `Viewer` (`MermaidBlock`, `GraphvizBlock`), their popout, and whatever a host renders itself. `DiagramViewer` from `@plannotator/ui/components/diagram` takes `kind`, `source`, `theme` (`{ colorTheme, mode, shadowAmount? }`), `comments: DiagramComment[]` and `onCreateComment(anchor, text, additionalTargets)`; pass `onSave(source) => Promise<{ status: 'ok' } | { status: 'stale', currentSource }>` to get the Source pane (left of the canvas on desktop, under it on the phone; `readOnlySource` shows it without Save), and `sourceOpen` to toggle it. Zoom, pan and fit are the canvas's (wheel, drag, `+` `-` `0`, arrow keys); a click opens the composer at the part beneath while a drag pans (4 px threshold, 10 px for a finger), nothing highlights on a plain mouse-over (the ring under the pointer needs the platform modifier held), every edge carries an invisible 14 px hit path in one top layer and a click is resolved by priority over everything under the pointer (node, then edge, then cluster; an edge label is its edge), a click on no part comments on the whole diagram (kind `diagram`), sequence diagrams are addressable (actors, messages, notes, frames), a saved comment paints a ring and a numbered badge from the array order, and every comment re-resolves against each render through the engine's finder (id, then label, then unanchored — reported through `onUnanchoredChange`). The anchor is `DiagramAnchor` from `@plannotator/core/diagram-anchor` (`{ v: 1, family, kind, id | from + to, label, sourceLine }`, document lines), and Plannotator stores it as `Annotation.diagramAnchor`. Runtime slots: `utils/mermaid` (as before) and `utils/graphviz` (new, same shape, `@viz-js/viz` pinned `3.30.0`), each lazy on first use or filled by the host. `DiagramPopout` is the full-size viewer in the `PopoutDialog` chrome. See HANDOFF.md § "Diagram engine (0.41.0)" for every export, the adapter, the sanitizer and the migration notes.
 
 ### WebMCP provider (`@plannotator/ui/webmcp`; 0.32.0)
 
diff --git a/packages/ui/components/DiagramBlock.tsx b/packages/ui/components/DiagramBlock.tsx
index 6bba8c642..caa9a54ea 100644
--- a/packages/ui/components/DiagramBlock.tsx
+++ b/packages/ui/components/DiagramBlock.tsx
@@ -2,7 +2,9 @@ import React, { lazy, Suspense, useCallback, useContext, useEffect, useMemo, use
 import { diagramTargetText, type DiagramKind } from '@plannotator/core/diagram-anchor';
 import type { AnnotationRestoreReport } from '../hooks/useAnnotationHighlighter';
 import { AnnotationType, type Annotation, type Block } from '../types';
+import { useConfigValue } from '../config';
 import type { DiagramTheme } from '../utils/diagram-render';
+import { diagramShadowAmount } from '../utils/diagramShadow';
 import { getIdentity } from '../utils/identity';
 import { createRuntimeRetryEpoch } from '../utils/runtimeRetry';
 import { DiagramAnchorClaims, DiagramAnchorClaimsContext } from './diagram/anchorClaims';
@@ -103,9 +105,17 @@ export const DiagramBlock: React.FC<DiagramBlockProps & { kind: DiagramKind }> =
   // provider renders exactly as before. A key change re-runs the render,
   // which is what re-themes an already rendered diagram.
   const { colorTheme, resolvedMode } = useTheme();
+  // The node shadow reaches the renderer the same way the palette does: as
+  // part of the theme key, so changing it re-initializes Mermaid and re-renders
+  // every mounted diagram.
+  const diagramShadow = useConfigValue('diagramShadow');
   const theme = useMemo<DiagramTheme>(
-    () => ({ colorTheme, mode: resolvedMode === 'light' ? 'light' : 'dark' }),
-    [colorTheme, resolvedMode],
+    () => ({
+      colorTheme,
+      mode: resolvedMode === 'light' ? 'light' : 'dark',
+      shadowAmount: diagramShadowAmount(diagramShadow),
+    }),
+    [colorTheme, resolvedMode, diagramShadow],
   );
 
   // A sibling's Retry re-attempts this block too, but only while its own
diff --git a/packages/ui/components/MermaidBlock.theme.test.tsx b/packages/ui/components/MermaidBlock.theme.test.tsx
index 42f83bad9..70f34a4e6 100644
--- a/packages/ui/components/MermaidBlock.theme.test.tsx
+++ b/packages/ui/components/MermaidBlock.theme.test.tsx
@@ -21,6 +21,8 @@
 import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, test } from 'bun:test';
 import React, { act } from 'react';
 import { createRoot, type Root } from 'react-dom/client';
+import { configStore } from '../config';
+import { DEFAULT_DIAGRAM_SHADOW } from '../utils/diagramShadow';
 import type { Block } from '../types';
 import { installInertDiagramSvgParser } from '../test-setup/diagramSvg';
 import { MermaidBlock, __setMermaidRuntimeLoaderForTests } from './MermaidBlock';
@@ -185,6 +187,36 @@ describe('MermaidBlock theming', () => {
     expect(svgCount()).toBe(2);
   });
 
+  test.skipIf(!hasDom)('the diagram shadow setting reaches the runtime and re-renders mounted diagrams', async () => {
+    const { runtime, recorded } = fakeRuntime();
+    __setMermaidRuntimeLoaderForTests(async () => runtime, { retryDelayMs: 5 });
+
+    await mount(<MermaidBlock block={block} />);
+    await settle();
+
+    const first = recorded.initialize[0] as { themeVariables: Record<string, unknown> };
+    // The shipped default: a toned-down shadow derived from the palette.
+    expect(first.themeVariables.dropShadow as string).toStartWith('drop-shadow(0.79px ');
+
+    try {
+      await act(async () => {
+        configStore.set('diagramShadow', 0);
+      });
+      await settle();
+
+      expect(recorded.initialize).toHaveLength(2);
+      const off = recorded.initialize[1] as { themeVariables: Record<string, unknown> };
+      expect(off.themeVariables.dropShadow).toBe(false);
+      // The mounted diagram was re-rendered, not left on the old shadow.
+      expect(recorded.renders).toBe(2);
+      expect(svgCount()).toBe(1);
+    } finally {
+      await act(async () => {
+        configStore.set('diagramShadow', DEFAULT_DIAGRAM_SHADOW);
+      });
+    }
+  });
+
   test.skipIf(!hasDom)('without theme tokens on the document the runtime is never re-initialized (host fallback)', async () => {
     styleEl?.remove();
     styleEl = null;
diff --git a/packages/ui/components/Settings.tsx b/packages/ui/components/Settings.tsx
index f58a305bf..dc5740a4d 100644
--- a/packages/ui/components/Settings.tsx
+++ b/packages/ui/components/Settings.tsx
@@ -6,6 +6,7 @@ import type { DiffLineBgIntensity } from '@plannotator/core/config-types';
 import type { TokenHoverDelay } from '@plannotator/core/token-hover';
 import { configStore, useConfigValue, setReviewPanelView, setReviewDefaultDiffType, setReviewAutoViewed } from '../config';
 import { setWebMcpToolsEnabled, useWebMcpToolsEnabled } from '../webmcp/preference';
+import { DIAGRAM_SHADOW_OPTIONS } from '../utils/diagramShadow';
 import { loadDiffFont } from '../utils/diffFonts';
 import { TaterSpritePullup } from './TaterSpritePullup';
 import { getIdentity, regenerateIdentity, setCustomIdentity, isIdentityEditable } from '../utils/identity';
@@ -959,6 +960,7 @@ export const Settings: React.FC<SettingsProps> = ({ taterMode, onTaterModeChange
   }, [themePreview]);
   const [activeTab, setActiveTab] = useState<SettingsTab>('general');
   const gridEnabled = useConfigValue('gridEnabled');
+  const diagramShadow = useConfigValue('diagramShadow');
   const vimModeEnabled = useConfigValue('vimModeEnabled');
   const vimHudEnabled = useConfigValue('vimHudEnabled');
   const vimHudKeyPanelEnabled = useConfigValue('vimHudKeyPanelEnabled');
@@ -1656,6 +1658,34 @@ export const Settings: React.FC<SettingsProps> = ({ taterMode, onTaterModeChange
 
                     <div className="border-t border-border" />
 
+                    {/* Diagram Shadow */}
+                    <div className="space-y-3" data-diagram-shadow-setting>
+                      <div>
+                        <div className="text-sm font-medium">Diagram Shadow</div>
+                        <div className="text-xs text-muted-foreground">
+                          Drop shadow under diagram nodes (100 = Mermaid's own)
+                        </div>
+                      </div>
+                      <div className="flex items-center gap-1 bg-muted/50 rounded-lg p-0.5">
+                        {DIAGRAM_SHADOW_OPTIONS.map((value) => (
+                          <button
+                            key={value}
+                            onClick={() => configStore.set('diagramShadow', value)}
+                            aria-pressed={diagramShadow === value}
+                            className={`flex-1 px-3 py-1.5 text-xs rounded-md transition-colors ${
+                              diagramShadow === value
+                                ? 'bg-background text-foreground shadow-sm font-medium'
+                                : 'text-muted-foreground hover:text-foreground'
+                            }`}
+                          >
+                            {value === 0 ? 'None' : String(value)}
+                          </button>
+                        ))}
+                      </div>
+                    </div>
+
+                    <div className="border-t border-border" />
+
                     {/* Plan Width */}
                     <div className="space-y-3">
                       <div>
diff --git a/packages/ui/config/diagramShadowSetting.test.ts b/packages/ui/config/diagramShadowSetting.test.ts
new file mode 100644
index 000000000..eeba71181
--- /dev/null
+++ b/packages/ui/config/diagramShadowSetting.test.ts
@@ -0,0 +1,68 @@
+/**
+ * The diagram shadow setting.
+ *
+ * The failure this guards is specific and was real during development: 0 is a
+ * VALID stored amount here, and `Number(null)` is 0, so a `fromCookie` that
+ * parses before checking for an absent cookie reads "never chosen" as "no
+ * shadow" — every diagram would ship flat, for everyone, with no way to tell
+ * the default from a choice. The rest pins the registry contract the Settings
+ * UI and `DiagramBlock` read through.
+ */
+import { afterEach, describe, expect, test } from 'bun:test';
+import { resetStorageBackend, setStorageBackend } from '../utils/storage';
+import { DEFAULT_DIAGRAM_SHADOW, DIAGRAM_SHADOW_OPTIONS, diagramShadowAmount } from '../utils/diagramShadow';
+import { SETTINGS } from './settings';
+
+const KEY = 'plannotator-diagram-shadow';
+
+function installBackend(seed: Record<string, string> = {}): Map<string, string> {
+  const values = new Map(Object.entries(seed));
+  setStorageBackend({
+    getItem: (key) => values.get(key) ?? null,
+    setItem: (key, value) => { values.set(key, value); },
+    removeItem: (key) => { values.delete(key); },
+  });
+  return values;
+}
+
+afterEach(() => {
+  resetStorageBackend();
+});
+
+describe('diagramShadow', () => {
+  test('an absent cookie is undefined, not 0', () => {
+    installBackend();
+    expect(SETTINGS.diagramShadow.fromCookie()).toBeUndefined();
+    installBackend({ [KEY]: '' });
+    expect(SETTINGS.diagramShadow.fromCookie()).toBeUndefined();
+    // Deliberate default: the shipped look is the toned-down shadow, not none.
+    expect(SETTINGS.diagramShadow.defaultValue).toBe(DEFAULT_DIAGRAM_SHADOW);
+  });
+
+  test('round-trips every offered step, 0 included, and rejects anything else', () => {
+    const values = installBackend();
+    for (const step of DIAGRAM_SHADOW_OPTIONS) {
+      SETTINGS.diagramShadow.toCookie(step);
+      expect(values.get(KEY)).toBe(String(step));
+      expect(SETTINGS.diagramShadow.fromCookie()).toBe(step);
+    }
+    for (const bad of ['-10', '101', '70.5', 'lots']) {
+      values.set(KEY, bad);
+      expect(SETTINGS.diagramShadow.fromCookie()).toBeUndefined();
+    }
+  });
+
+  test('the stored percent becomes the 0..1 amount the mapping takes', () => {
+    expect(diagramShadowAmount(0)).toBe(0);
+    expect(diagramShadowAmount(70)).toBe(0.7);
+    expect(diagramShadowAmount(100)).toBe(1);
+    // Nothing downstream ever sees an out-of-range amount.
+    expect(diagramShadowAmount(-5)).toBe(0);
+    expect(diagramShadowAmount(400)).toBe(1);
+    expect(diagramShadowAmount(Number.NaN)).toBe(DEFAULT_DIAGRAM_SHADOW / 100);
+  });
+
+  test('it is cookie-only: no server key, so it never writes ~/.plannotator/config.json', () => {
+    expect(SETTINGS.diagramShadow.serverKey).toBeUndefined();
+  });
+});
diff --git a/packages/ui/config/settings.ts b/packages/ui/config/settings.ts
index a748ad912..82f4a4454 100644
--- a/packages/ui/config/settings.ts
+++ b/packages/ui/config/settings.ts
@@ -22,6 +22,7 @@ import {
   type TokenHoverDelay,
   type TokenHoverTrigger,
 } from '@plannotator/core/token-hover';
+import { DEFAULT_DIAGRAM_SHADOW, isDiagramShadow } from '../utils/diagramShadow';
 import { storage } from '../utils/storage';
 import { generateIdentity } from '../utils/generateIdentity';
 import {
@@ -170,6 +171,27 @@ export const SETTINGS = {
     serverKey: undefined, fromServer: undefined, toServer: undefined,
   },
 
+  /**
+   * How strong the drop shadow under Mermaid diagram nodes is, 0..100, where
+   * 100 is Mermaid 12's own default geometry. Default 70: the shipped neo look
+   * with its halo toned down (the colour is always derived from the palette,
+   * see `utils/mermaidTheme`). Cookie-only, like the other display knobs.
+   */
+  diagramShadow: {
+    defaultValue: DEFAULT_DIAGRAM_SHADOW as number,
+    fromCookie: () => {
+      // `Number(null)` and `Number('')` are 0, which is a VALID amount here
+      // (unlike the token-hover steps), so an absent cookie must be rejected
+      // before the guard sees it — otherwise no cookie reads as "no shadow".
+      const raw = storage.getItem('plannotator-diagram-shadow');
+      if (raw === null || raw.trim() === '') return undefined;
+      const parsed = Number(raw);
+      return isDiagramShadow(parsed) ? parsed : undefined;
+    },
+    toCookie: (value: number) => storage.setItem('plannotator-diagram-shadow', String(value)),
+    serverKey: undefined, fromServer: undefined, toServer: undefined,
+  },
+
   vimModeEnabled: {
     // Vim bindings deliberately default OFF. Unmodified letter keys must remain
     // inert for existing users until they explicitly opt into modal document
diff --git a/packages/ui/package.json b/packages/ui/package.json
index 0a8ee45e9..7786f1940 100644
--- a/packages/ui/package.json
+++ b/packages/ui/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@plannotator/ui",
-  "version": "0.41.1",
+  "version": "0.41.2",
   "type": "module",
   "exports": {
     "./components/*": "./components/*.tsx",
diff --git a/packages/ui/utils/diagram-render.ts b/packages/ui/utils/diagram-render.ts
index 21a04c62b..5b33581b5 100644
--- a/packages/ui/utils/diagram-render.ts
+++ b/packages/ui/utils/diagram-render.ts
@@ -48,14 +48,21 @@ type Mermaid = Awaited<ReturnType<typeof loadMermaidRuntime>>;
 
 /**
  * The (palette, mode) a render is for: the same pair `useTheme()` resolves
- * for code fences. The mermaid entry passes it to `applyMermaidTheme`, which
- * runs the global `initialize` once per key; the graphviz entry recolors its
- * defaults onto CSS tokens and needs neither. A host without ThemeProvider
- * passes any palette id with the mode it renders in.
+ * for code fences, plus the node shadow amount the user chose. The mermaid
+ * entry passes them to `applyMermaidTheme`, which runs the global `initialize`
+ * once per key; the graphviz entry recolors its defaults onto CSS tokens and
+ * needs neither. A host without ThemeProvider passes any palette id with the
+ * mode it renders in.
  */
 export interface DiagramTheme {
   readonly colorTheme: string;
   readonly mode: MermaidThemeMode;
+  /**
+   * Node drop shadow strength, 0..1 (see `mermaidTheme.buildMermaidShadow`).
+   * Absent means the shipped default, so a host that builds its own
+   * `DiagramTheme` renders exactly what Plannotator renders.
+   */
+  readonly shadowAmount?: number;
 }
 
 export type DiagramRenderError = {
@@ -514,11 +521,11 @@ const mermaidRenderer: DiagramRenderer = {
     }
     // Derive every Mermaid theme variable from the page's tokens before each
     // render, so the diagram follows the palette and mode. Keyed on the
-    // runtime plus (palette, mode), so the lazy runtime is themed on its
-    // first render and re-initialized only when one of the three changes.
+    // runtime plus (palette, mode, shadow amount), so the lazy runtime is
+    // themed on its first render and re-initialized only when one changes.
     // With no tokens on the page it is a no-op and the static
     // MERMAID_CONFIG (securityLevel strict) applies.
-    applyMermaidTheme(runtime, mermaidThemeKey(theme.colorTheme, theme.mode));
+    applyMermaidTheme(runtime, mermaidThemeKey(theme.colorTheme, theme.mode, theme.shadowAmount));
     return renderMermaid(runtime, renderId, source);
   },
 };
diff --git a/packages/ui/utils/diagramShadow.ts b/packages/ui/utils/diagramShadow.ts
new file mode 100644
index 000000000..69b6aadb5
--- /dev/null
+++ b/packages/ui/utils/diagramShadow.ts
@@ -0,0 +1,27 @@
+/**
+ * The user-facing scale for the Mermaid node drop shadow: whole percent, 0..100,
+ * where 100 is Mermaid 12's own default shadow and 0 is none.
+ *
+ * Deliberately free of imports so the settings registry can read it on every
+ * surface (the guides.show viewer included) without pulling the diagram theme
+ * mapping — and the runtime into which it feeds — into that module graph.
+ * `mermaidTheme.DEFAULT_MERMAID_SHADOW_AMOUNT` is the same value in the 0..1
+ * unit the mapping takes; `mermaidTheme.test.ts` pins the two together.
+ */
+
+/** The steps Settings offers. A slider would imply a precision nobody can see. */
+export const DIAGRAM_SHADOW_OPTIONS = [0, 40, 70, 100] as const;
+
+/** Shipped default: the neo look with its grey halo toned down. */
+export const DEFAULT_DIAGRAM_SHADOW = 70;
+
+/** Any whole percent in range is valid, not only the offered steps. */
+export function isDiagramShadow(value: unknown): value is number {
+  return typeof value === 'number' && Number.isInteger(value) && value >= 0 && value <= 100;
+}
+
+/** The 0..1 amount `buildMermaidThemeVariables` takes. */
+export function diagramShadowAmount(percent: number): number {
+  if (!Number.isFinite(percent)) return DEFAULT_DIAGRAM_SHADOW / 100;
+  return Math.min(100, Math.max(0, percent)) / 100;
+}
diff --git a/packages/ui/utils/mermaid.ts b/packages/ui/utils/mermaid.ts
index fd371dc7b..4e7f85ce3 100644
--- a/packages/ui/utils/mermaid.ts
+++ b/packages/ui/utils/mermaid.ts
@@ -45,6 +45,18 @@ export const MERMAID_CONFIG: MermaidConfig = {
     clusterBorder: '#475569',
     titleColor: '#f8fafc',
     edgeLabelBackground: '#1e293b',
+    /**
+     * Mermaid 12's neo look shadows every node from a fixed
+     * `drop-shadow(1px 2px 2px rgba(185,185,185,1))` grey, which reads as a
+     * halo. The token-driven mapping replaces it per palette
+     * (`buildMermaidShadow` in `./mermaidTheme`); this static config is what a
+     * host with no theme tokens renders with, so it carries the same
+     * toned-down 0.7 geometry with a fixed colour. The value is what
+     * `buildMermaidShadow(#1e293b, 0.7)` returns for THIS config's own slate
+     * ground, which is dark — hence a light shadow, exactly as Mermaid's own
+     * `insertLookDefs` uses a white flood colour on dark themes.
+     */
+    dropShadow: 'drop-shadow(0.79px 1.58px 1.58px rgba(210, 212, 217, 0.684))',
   },
   flowchart: {
     htmlLabels: true,
diff --git a/packages/ui/utils/mermaidTheme.test.ts b/packages/ui/utils/mermaidTheme.test.ts
index bf7474b9d..cffd6f007 100644
--- a/packages/ui/utils/mermaidTheme.test.ts
+++ b/packages/ui/utils/mermaidTheme.test.ts
@@ -19,22 +19,49 @@ import { describe, expect, test } from 'bun:test';
 import { readdirSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { MERMAID_CONFIG } from './mermaid';
-import { contrastRatio, parseCssColor, toHex } from './cssColor';
+import { compositeOver, contrastRatio, parseCssColor, relativeLuminance, toHex, type RgbColor } from './cssColor';
+import { DEFAULT_DIAGRAM_SHADOW, DIAGRAM_SHADOW_OPTIONS } from './diagramShadow';
 import {
+  DEFAULT_MERMAID_SHADOW_AMOUNT,
   MERMAID_LINE_CONTRAST_MIN,
   MERMAID_TEXT_CONTRAST_MIN,
   __resetMermaidThemeForTests,
   applyMermaidTheme,
   buildMermaidConfig,
+  buildMermaidShadow,
   buildMermaidThemeVariables,
   ensureContrast,
+  isDarkBackground,
   mermaidThemeKey,
+  shadowAmountFromKey,
   type MermaidThemeMode,
   type MermaidThemeTokens,
 } from './mermaidTheme';
 
 const HEX = /^#[0-9a-f]{6}$/;
 
+/**
+ * Every shipped palette, both modes. Reads the tokens straight out of the CSS
+ * so a palette added later is swept automatically (by the contrast guard AND
+ * by the shadow sweep below).
+ */
+const themesDir = join(import.meta.dir, '..', 'themes');
+const themeFiles = readdirSync(themesDir).filter((f) => f.endsWith('.css')).sort();
+expect(themeFiles.length).toBeGreaterThan(30);
+
+/** First rule whose selector list names `selector` (some files write `.theme-x,\n.theme-x.light {`). */
+function tokensFromCss(css: string, selector: string): MermaidThemeTokens | undefined {
+  const stripped = css.replace(/\/\*[\s\S]*?\*\//g, '');
+  for (const rule of stripped.matchAll(/([^{}]+)\{([^}]*)\}/g)) {
+    const selectors = rule[1].split(',').map((sel) => sel.trim());
+    if (!selectors.includes(selector)) continue;
+    const tokens: Record<string, string> = {};
+    for (const m of rule[2].matchAll(/--([a-z-]+)\s*:\s*([^;]+);/g)) tokens[m[1]] = m[2].trim();
+    return tokens as MermaidThemeTokens;
+  }
+  return undefined;
+}
+
 /** The Plannotator base palette, as `themes/plannotator.css` writes it. */
 const PLANNOTATOR_DARK: MermaidThemeTokens = {
   background: 'oklch(0.15 0.02 260)',
@@ -258,27 +285,6 @@ describe('contrast guard', () => {
     expect(ratio(vars, 'nodeBorder', 'background')).toBeGreaterThanOrEqual(1.5);
   });
 
-  /**
-   * Every shipped palette, both modes. Reads the tokens straight out of the
-   * CSS so a palette added later is swept automatically.
-   */
-  const themesDir = join(import.meta.dir, '..', 'themes');
-  const themeFiles = readdirSync(themesDir).filter((f) => f.endsWith('.css')).sort();
-  expect(themeFiles.length).toBeGreaterThan(30);
-
-  /** First rule whose selector list names `selector` (some files write `.theme-x,\n.theme-x.light {`). */
-  function tokensFromCss(css: string, selector: string): MermaidThemeTokens | undefined {
-    const stripped = css.replace(/\/\*[\s\S]*?\*\//g, '');
-    for (const rule of stripped.matchAll(/([^{}]+)\{([^}]*)\}/g)) {
-      const selectors = rule[1].split(',').map((sel) => sel.trim());
-      if (!selectors.includes(selector)) continue;
-      const tokens: Record<string, string> = {};
-      for (const m of rule[2].matchAll(/--([a-z-]+)\s*:\s*([^;]+);/g)) tokens[m[1]] = m[2].trim();
-      return tokens as MermaidThemeTokens;
-    }
-    return undefined;
-  }
-
   const TEXT_PAIRS: Array<[string, string]> = [
     ['primaryTextColor', 'nodeBkg'],
     ['nodeTextColor', 'nodeBkg'],
@@ -385,3 +391,124 @@ describe('applyMermaidTheme', () => {
     }
   });
 });
+
+/**
+ * Node drop shadow (the `dropShadow` theme variable).
+ *
+ * What regresses if these fail:
+ * - the shipped look changes: Mermaid 12's neo shadow comes back at full
+ *   strength (the grey halo), or disappears entirely;
+ * - the shadow is derived in the wrong polarity, which on a dark page paints a
+ *   black shadow on a near-black ground — a valid filter that renders nothing,
+ *   the exact bug the lab found;
+ * - a shadow amount stops reaching the runtime because the cache key ignores
+ *   it, so the setting silently does nothing until the palette changes;
+ * - the shadow leaks into a fill or a label colour (it is a paint-time filter
+ *   and must touch nothing else).
+ */
+describe('node shadow', () => {
+  /** The `rgba(r, g, b, a)` inside a `drop-shadow(x y blur rgba(...))`. */
+  function shadowColor(filter: string): { color: RgbColor; alpha: number } {
+    const m = /rgba\((\d+),\s*(\d+),\s*(\d+),\s*([\d.]+)\)/u.exec(filter);
+    if (!m) throw new Error(`no rgba in ${filter}`);
+    return {
+      color: { r: Number(m[1]) / 255, g: Number(m[2]) / 255, b: Number(m[3]) / 255, a: 1 },
+      alpha: Number(m[4]),
+    };
+  }
+
+  test('the setting scale and the mapping amount are the same number', () => {
+    expect(DEFAULT_DIAGRAM_SHADOW / 100).toBe(DEFAULT_MERMAID_SHADOW_AMOUNT);
+    expect(DIAGRAM_SHADOW_OPTIONS).toContain(DEFAULT_DIAGRAM_SHADOW);
+  });
+
+  test('amount 1 reproduces Mermaid 12 own geometry, 0.7 is the shipped toning', () => {
+    const ground = parseCssColor('#111318')!;
+    expect(buildMermaidShadow(ground, 1)).toStartWith('drop-shadow(1px 2px 2px ');
+    expect(buildMermaidShadow(ground, 0.7)).toStartWith('drop-shadow(0.79px 1.58px 1.58px ');
+    expect(buildMermaidShadow(ground, 0)).toBe(false);
+    // Out of range is clamped, not trusted.
+    expect(buildMermaidShadow(ground, 4)).toBe(buildMermaidShadow(ground, 1));
+    expect(buildMermaidShadow(ground, -1)).toBe(false);
+  });
+
+  test('a ground the palette could not produce falls back to Mermaid own colour', () => {
+    expect(buildMermaidShadow(undefined, 0.7)).toContain('rgba(185, 185, 185, 1)');
+  });
+
+  test('amount 0 publishes no shadow at all, including the state dots', () => {
+    const spec = buildMermaidThemeVariables(PLANNOTATOR_DARK, 'dark', { shadowAmount: 0 })!;
+    expect(spec.themeVariables.dropShadow).toBe(false);
+    expect(spec.themeVariables.nodeShadow).toBe(false);
+    expect(spec.shadowAmount).toBe(0);
+  });
+
+  /**
+   * Fill / label fingerprint: every variable the mapping produces EXCEPT the
+   * two shadow keys, at amount 0 against the shipped 70. The shadow is a
+   * paint-time filter; if a change to it ever moved a fill or a label colour,
+   * this is what catches it.
+   */
+  const fingerprint = (vars: Record<string, unknown>) =>
+    Object.entries(vars)
+      .filter(([k]) => k !== 'dropShadow' && k !== 'nodeShadow')
+      .map(([k, v]) => `${k}=${JSON.stringify(v)}`)
+      .sort()
+      .join('\n');
+
+  test('the shadow touches nothing but the shadow', () => {
+    for (const [tokens, mode] of [
+      [PLANNOTATOR_DARK, 'dark'],
+      [PLANNOTATOR_LIGHT, 'light'],
+    ] as Array<[MermaidThemeTokens, MermaidThemeMode]>) {
+      const off = buildMermaidThemeVariables(tokens, mode, { shadowAmount: 0 })!.themeVariables;
+      const on = buildMermaidThemeVariables(tokens, mode)!.themeVariables;
+      expect(fingerprint(on)).toBe(fingerprint(off));
+    }
+  });
+
+  test('the cache key carries the amount, and the default key is the old (palette, mode) key', () => {
+    expect(mermaidThemeKey('plannotator', 'dark')).toBe('dark:plannotator');
+    expect(mermaidThemeKey('plannotator', 'dark', DEFAULT_MERMAID_SHADOW_AMOUNT)).toBe('dark:plannotator');
+    expect(mermaidThemeKey('plannotator', 'dark', 0)).not.toBe('dark:plannotator');
+    expect(mermaidThemeKey('plannotator', 'dark', 0)).not.toBe(mermaidThemeKey('plannotator', 'dark', 0.4));
+    expect(shadowAmountFromKey(mermaidThemeKey('plannotator', 'dark', 0.4))).toBe(0.4);
+    expect(shadowAmountFromKey(mermaidThemeKey('plannotator', 'dark'))).toBe(DEFAULT_MERMAID_SHADOW_AMOUNT);
+    // A palette id is never mistaken for an amount.
+    expect(shadowAmountFromKey('light:one-light')).toBe(DEFAULT_MERMAID_SHADOW_AMOUNT);
+  });
+
+  /** Every shipped palette, both modes: a shadow at the default, in the direction that reads. */
+  for (const file of themeFiles) {
+    const css = readFileSync(join(themesDir, file), 'utf8');
+    const id = file.replace(/\.css$/, '');
+    for (const mode of ['dark', 'light'] as MermaidThemeMode[]) {
+      const selector = mode === 'dark' ? `.theme-${id}` : `.theme-${id}.light`;
+      const tokens = tokensFromCss(css, selector);
+      test(`${id} / ${mode}: a default shadow that differs from the ground in the readable direction`, () => {
+        expect(tokens, `${selector} block in ${file}`).toBeDefined();
+        const spec = buildMermaidThemeVariables(tokens, mode)!;
+        expect(spec.shadowAmount).toBe(DEFAULT_MERMAID_SHADOW_AMOUNT);
+        const filter = spec.themeVariables.dropShadow;
+        expect(typeof filter).toBe('string');
+        expect(filter as string).toStartWith('drop-shadow(0.79px 1.58px 1.58px ');
+        const ground = compositeOver(parseCssColor(tokens!.background!)!, { r: 1, g: 1, b: 1, a: 1 });
+        const { color, alpha } = shadowColor(filter as string);
+        const groundL = relativeLuminance(ground);
+        if (isDarkBackground(ground)) {
+          // A shadow on a dark page LIFTS: darker than the ground is invisible.
+          expect(relativeLuminance(color)).toBeGreaterThan(groundL);
+          expect(alpha).toBeCloseTo(0.684, 3);
+        } else {
+          expect(relativeLuminance(color)).toBeLessThan(groundL);
+          expect(alpha).toBeCloseTo(0.46, 3);
+        }
+        // Never Mermaid's fixed grey: the tint comes from the palette.
+        expect(filter as string).not.toContain('185, 185, 185');
+        // Fills and labels are identical with the shadow off: paint only.
+        const off = buildMermaidThemeVariables(tokens, mode, { shadowAmount: 0 })!.themeVariables;
+        expect(fingerprint(spec.themeVariables)).toBe(fingerprint(off));
+      });
+    }
+  }
+});
diff --git a/packages/ui/utils/mermaidTheme.ts b/packages/ui/utils/mermaidTheme.ts
index c158a0931..556cd4151 100644
--- a/packages/ui/utils/mermaidTheme.ts
+++ b/packages/ui/utils/mermaidTheme.ts
@@ -24,7 +24,18 @@
  *    Mermaid's colour library does not parse `oklch()`.
  * 3. `applyMermaidTheme(mermaid, key)` is the runtime step `MermaidBlock`
  *    calls before every render: `mermaid.initialize` is global state, so it
- *    runs only when the `(palette, mode)` key changed since the last apply.
+ *    runs only when the `(palette, mode, shadow amount)` key changed since the
+ *    last apply.
+ *
+ * Node shadow: Mermaid 12's neo look paints a drop shadow on every node,
+ * cluster and actor, from its own fixed `rgba(185,185,185,1)` grey at
+ * `1px 2px 2px`. The mapping keeps the look and replaces that one filter:
+ * `themeVariables.dropShadow` is built from the palette's own ground at
+ * `DEFAULT_MERMAID_SHADOW_AMOUNT` (0.7 of Mermaid's geometry), in the polarity
+ * the page reads in — see `buildMermaidShadow`. A host that wants Mermaid's
+ * grey back sets its own `themeVariables.dropShadow` after ours; a host that
+ * wants none passes `{ shadowAmount: 0 }`, which publishes `dropShadow: false`
+ * and the neo rules render `filter: none`.
  *
  * Fallback contract (hosts): when no tokens resolve, the runtime keeps the
  * static `MERMAID_CONFIG` it was initialized with, and nothing is
@@ -106,6 +117,35 @@ export type MermaidThemeTokens = Partial<Record<MermaidThemeTokenName, string>>;
 export interface MermaidThemeSpec {
   theme: 'dark' | 'default';
   themeVariables: Record<string, unknown>;
+  /** The node shadow amount baked into `themeVariables.dropShadow` (0..1). */
+  shadowAmount: number;
+}
+
+/** Options `buildMermaidThemeVariables` accepts beyond the tokens and mode. */
+export interface MermaidThemeOptions {
+  /**
+   * How much node drop shadow to paint, 0..1, where 1 reproduces Mermaid's
+   * own default geometry (`1px 2px 2px`) and 0 means no shadow at all.
+   * Default: `DEFAULT_MERMAID_SHADOW_AMOUNT`.
+   */
+  readonly shadowAmount?: number;
+}
+
+/**
+ * The shipped shadow amount: Mermaid 12's neo look at 70% of its own shadow.
+ * The full-strength default reads as a grey halo around every node on a
+ * Plannotator page; 70 keeps the lift and drops the halo.
+ */
+export const DEFAULT_MERMAID_SHADOW_AMOUNT = 0.7;
+
+/** Mermaid 12's own node shadow, the colour included. Amount 1 reproduces
+ *  this geometry; the colour is ours unless the palette yields nothing. */
+export const MERMAID_DEFAULT_SHADOW_COLOR = 'rgba(185, 185, 185, 1)';
+
+/** Clamp an amount to 0..1 and round it, so it is stable in a cache key. */
+export function clampShadowAmount(amount: number | undefined): number {
+  if (typeof amount !== 'number' || !Number.isFinite(amount)) return DEFAULT_MERMAID_SHADOW_AMOUNT;
+  return Math.round(Math.min(1, Math.max(0, amount)) * 1000) / 1000;
 }
 
 /** WCAG minimums the guard enforces. */
@@ -317,6 +357,62 @@ export function isDarkBackground(background: RgbColor): boolean {
   return relativeLuminance(background) < 0.179;
 }
 
+/** `rgba()` from an RgbColor plus an explicit alpha. */
+function rgba(c: RgbColor, alpha: number): string {
+  const ch = (v: number) => Math.round(Math.max(0, Math.min(1, v)) * 255);
+  return `rgba(${ch(c.r)}, ${ch(c.g)}, ${ch(c.b)}, ${Math.round(alpha * 1000) / 1000})`;
+}
+
+/**
+ * The node drop shadow, as the `drop-shadow(x y blur colour)` string Mermaid's
+ * `dropShadow` theme variable takes, or `false` — its falsy value, which every
+ * `[data-look="neo"] … { filter: … }` rule turns into `filter: none`.
+ *
+ * Geometry scales with the amount over a small floor, so a toned-down shadow
+ * still reads as a lift rather than vanishing: at 1 it is exactly Mermaid's own
+ * `1px 2px 2px`, at 0 there is no shadow at all.
+ *
+ * The COLOUR comes from the palette rather than Mermaid's fixed
+ * `rgba(185,185,185,1)` grey — that grey is the halo that reads as wrong on a
+ * themed page — and its POLARITY follows the page, exactly as Mermaid's own
+ * `insertLookDefs` does (`floodColor = theme.includes('dark') ? '#FFFFFF' :
+ * '#000000'`): on a dark page a shadow's job is to LIFT the node off the
+ * ground, and a black shadow on a near-black ground paints nothing the eye can
+ * see. What is kept from the palette is the tint and the strength, not the
+ * direction:
+ *   - dark page: the ground lifted 82% toward white, alpha 0.18 -> 0.90;
+ *   - light page: the ground darkened 40% toward black, alpha 0.25 -> 0.55.
+ * Each is then asserted to differ from the ground in the READABLE direction,
+ * falling back to plain white or black, so no palette can produce an invisible
+ * shadow; a ground that is not a usable colour at all falls back to Mermaid's
+ * own grey.
+ *
+ * Pure. `ground` is the page's opaque background.
+ */
+export function buildMermaidShadow(ground: RgbColor | undefined, amount: number): string | false {
+  const a = clampShadowAmount(amount);
+  if (a <= 0) return false;
+  const round = (v: number) => Math.round(v * 100) / 100;
+  const geometry = `${round(0.3 + 0.7 * a)}px ${round(0.6 + 1.4 * a)}px ${round(0.6 + 1.4 * a)}px`;
+  const usable =
+    ground !== undefined &&
+    Number.isFinite(ground.r) &&
+    Number.isFinite(ground.g) &&
+    Number.isFinite(ground.b);
+  // Nothing usable from the palette: Mermaid's own colour at our geometry.
+  if (!usable) return `drop-shadow(${geometry} ${MERMAID_DEFAULT_SHADOW_COLOR})`;
+  const dark = isDarkBackground(ground);
+  let colour = dark ? mixOklab(ground, WHITE, 0.82) : mixOklab(ground, BLACK, 0.4);
+  // The dark-page top end is calibrated so amount 1 reads as strongly as
+  // Mermaid's own `rgba(185,185,185,1)` over the same ground — 1 is defined as
+  // "Mermaid's default", so it has to actually look like it.
+  const alpha = dark ? 0.18 + 0.72 * a : 0.25 + 0.3 * a;
+  const groundL = relativeLuminance(ground);
+  if (dark && relativeLuminance(colour) <= groundL) colour = WHITE;
+  if (!dark && relativeLuminance(colour) >= groundL) colour = BLACK;
+  return `drop-shadow(${geometry} ${rgba(colour, alpha)})`;
+}
+
 /**
  * Push a fill's lightness away from `ink` until `ink` reads on it at 4.5:1.
  * Used for the categorical scale, whose single ink is fixed per mode.
@@ -376,10 +472,15 @@ export function buildCategoricalScale(p: Palette, polarity: MermaidThemeMode): R
  * the tokens. Returns `null` when the required tokens are missing or
  * unparsable, which callers treat as "use the static config".
  */
-export function buildMermaidThemeVariables(tokens: MermaidThemeTokens | undefined, mode: MermaidThemeMode): MermaidThemeSpec | null {
+export function buildMermaidThemeVariables(
+  tokens: MermaidThemeTokens | undefined,
+  mode: MermaidThemeMode,
+  options?: MermaidThemeOptions,
+): MermaidThemeSpec | null {
   if (!tokens) return null;
   const p = resolvePalette(tokens);
   if (!p) return null;
+  const shadowAmount = clampShadowAmount(options?.shadowAmount);
 
   // Base theme follows the mode; fill lightness and ink follow the measured page.
   const polarity: MermaidThemeMode = isDarkBackground(p.background) ? 'dark' : 'light';
@@ -428,6 +529,9 @@ export function buildMermaidThemeVariables(tokens: MermaidThemeTokens | undefine
   const scaleLabel = scale.map((c) => toHex(text(scaleInk, c)));
 
   const h = toHex;
+  // The shadow nodes, clusters and actors are painted with. Derived from the
+  // page's own ground, never Mermaid's fixed grey (see buildMermaidShadow).
+  const shadow = buildMermaidShadow(p.background, shadowAmount);
   const vars: Record<string, unknown> = {
     darkMode: mode === 'dark',
     ...(p.fontFamily ? { fontFamily: p.fontFamily } : {}),
@@ -459,6 +563,13 @@ export function buildMermaidThemeVariables(tokens: MermaidThemeTokens | undefine
     errorBkgColor: h(errorBg),
     errorTextColor: h(errorText),
     useGradient: false,
+    // Paint-time only: a filter on the shape, never a fill or a label colour.
+    dropShadow: shadow,
+    // `nodeShadow` gates ONE thing in Mermaid 12: the inline
+    // `filter:url(#…-drop-shadow-small)` a state diagram's small start / end
+    // dots carry, which no theme variable string reaches. Off at amount 0 so
+    // "no shadow" is true of every element.
+    ...(shadow === false ? { nodeShadow: false } : {}),
 
     // Flowchart
     nodeBkg: h(p.card),
@@ -669,7 +780,7 @@ export function buildMermaidThemeVariables(tokens: MermaidThemeTokens | undefine
     vars[`fillType${i}`] = scaleHex[i];
     vars[`venn${i + 1}`] = scaleHex[i];
   }
-  return { theme: mode === 'dark' ? 'dark' : 'default', themeVariables: vars };
+  return { theme: mode === 'dark' ? 'dark' : 'default', themeVariables: vars, shadowAmount };
 }
 
 /** The full Mermaid config for a spec: `MERMAID_CONFIG` with the theme swapped. */
@@ -682,15 +793,33 @@ export function buildMermaidConfig(spec: MermaidThemeSpec | null): MermaidConfig
 // Runtime application (cached by key)
 // ---------------------------------------------------------------------------
 
-/** `mode:palette`, the cache key `applyMermaidTheme` compares. */
-export function mermaidThemeKey(colorTheme: string, mode: MermaidThemeMode): string {
-  return `${mode}:${colorTheme}`;
+/**
+ * `mode:palette`, the cache key `applyMermaidTheme` compares — plus a
+ * `#s<amount>` suffix when the shadow amount is not the shipped default, so a
+ * changed amount re-initializes the runtime. The default amount keeps the key
+ * byte-identical to the `(palette, mode)` pair it always was, which is also
+ * what keeps a host that never names an amount on the same key it had.
+ */
+export function mermaidThemeKey(
+  colorTheme: string,
+  mode: MermaidThemeMode,
+  shadowAmount: number = DEFAULT_MERMAID_SHADOW_AMOUNT,
+): string {
+  const amount = clampShadowAmount(shadowAmount);
+  const base = `${mode}:${colorTheme}`;
+  return amount === DEFAULT_MERMAID_SHADOW_AMOUNT ? base : `${base}#s${amount}`;
 }
 
 function modeFromKey(key: string): MermaidThemeMode {
   return key.startsWith('light:') ? 'light' : 'dark';
 }
 
+/** The amount a key carries, the default when it carries none. */
+export function shadowAmountFromKey(key: string): number {
+  const match = /#s(\d*\.?\d+)$/u.exec(key);
+  return match ? clampShadowAmount(Number(match[1])) : DEFAULT_MERMAID_SHADOW_AMOUNT;
+}
+
 export type MermaidThemeApplyResult = 'unchanged' | 'dynamic' | 'static';
 
 let appliedRuntime: Pick<Mermaid, 'initialize'> | null = null;
@@ -710,7 +839,9 @@ export function applyMermaidTheme(
   root?: Element | null,
 ): MermaidThemeApplyResult {
   if (appliedRuntime === mermaid && appliedKey === key) return 'unchanged';
-  const spec = buildMermaidThemeVariables(readThemeTokens(root), modeFromKey(key));
+  const spec = buildMermaidThemeVariables(readThemeTokens(root), modeFromKey(key), {
+    shadowAmount: shadowAmountFromKey(key),
+  });
   const sameRuntime = appliedRuntime === mermaid;
   appliedRuntime = mermaid;
   appliedKey = key;