create-zudo-doc 0.2.9 → 0.2.10

package/dist/features/image-enlarge.d.ts

@@ -12,7 +12,7 @@ import type { FeatureModule } from "../compose.js";
  * feature, the server-side figure/button emission is re-implemented via an
  * MDX paragraph (p) component override in pages/_mdx-components.ts. When
  * imageEnlarge is enabled, three injections into the template file install:
- *   1. Additional imports: toChildArray + VNode from preact, settings.
+ *   1. Additional imports: toChildArray + VNode from preact.
  *   2. ENLARGE_SVG const + EnlargeableParagraph function definition.
  *   3. `p: EnlargeableParagraph` entry in the createMdxComponents return map.
  * When imageEnlarge is OFF, none of these are injected, so the override is

package/dist/features/image-enlarge.js

@@ -11,7 +11,7 @@
  * feature, the server-side figure/button emission is re-implemented via an
  * MDX paragraph (p) component override in pages/_mdx-components.ts. When
  * imageEnlarge is enabled, three injections into the template file install:
- *   1. Additional imports: toChildArray + VNode from preact, settings.
+ *   1. Additional imports: toChildArray + VNode from preact.
  *   2. ENLARGE_SVG const + EnlargeableParagraph function definition.
  *   3. `p: EnlargeableParagraph` entry in the createMdxComponents return map.
  * When imageEnlarge is OFF, none of these are injected, so the override is
@@ -21,15 +21,17 @@
 export const imageEnlargeFeature = () => ({
     name: "imageEnlarge",
     injections: [
-        // 1. Import additions: toChildArray + VNode from preact, settings.
+        // 1. Import additions: toChildArray + VNode from preact.
         //    Inserted AFTER the `// @slot:mdx-components:enlarge-imports` anchor.
+        //    NOTE: `settings` is NOT injected here — the base template already
+        //    imports it (#2172); injecting it again caused a duplicate ES-module
+        //    lexical binding.
         {
             file: "pages/_mdx-components.ts",
             anchor: "// @slot:mdx-components:enlarge-imports",
             position: "after",
             content: `import { toChildArray } from "preact";
-import type { VNode } from "preact";
-import { settings } from "@/config/settings";`,
+import type { VNode } from "preact";`,
         },
         // 2. ENLARGE_SVG const + EnlargeableParagraph function.
         //    Inserted AFTER the `// @slot:mdx-components:enlarge-defs` anchor

package/dist/scaffold.js

@@ -178,7 +178,7 @@ export async function scaffold(choices) {
     await fs.outputFile(path.join(targetDir, "zfb.config.ts"), zfbConfigContent);
     const pkg = generatePackageJson(choices);
     await fs.outputFile(path.join(targetDir, "package.json"), JSON.stringify(pkg, null, 2) + "\n");
-    await fs.outputFile(path.join(targetDir, ".gitignore"), [
+    const gitignoreLines = [
         "# Build output",
         "node_modules",
         "dist",
@@ -201,7 +201,24 @@ export async function scaffold(choices) {
         "# Cloudflare Wrangler",
         ".wrangler/",
         "",
-    ].join("\n"));
+    ];
+    // The doc-lookup skill is only generated when skillSymlinker is selected
+    // (the setup-doc-skill.sh script and `setup:doc-skill` npm script are gated
+    // on the same feature above), so only emit its ignore entries then —
+    // otherwise they would be dead rules that could silently hide an unrelated
+    // skill a user later installs under a matching name. The skill name is
+    // deterministic (always `<projectName>-wisdom`, matching DEFAULT_SKILL_NAME
+    // in scripts/setup-doc-skill.sh and the package name), so these entries match
+    // the directory the script creates. The docs-ja symlink only exists for i18n
+    // projects (the script creates it conditionally), so gate that line on i18n.
+    if (choices.features.includes("skillSymlinker")) {
+        gitignoreLines.push("# Generated doc-lookup skill", `.claude/skills/${choices.projectName}-wisdom/SKILL.md`, `.claude/skills/${choices.projectName}-wisdom/docs`);
+        if (choices.features.includes("i18n")) {
+            gitignoreLines.push(`.claude/skills/${choices.projectName}-wisdom/docs-ja`);
+        }
+        gitignoreLines.push("");
+    }
+    await fs.outputFile(path.join(targetDir, ".gitignore"), gitignoreLines.join("\n"));
     // Emit an .npmrc exempting undici-types from pnpm's trust-downgrade policy.
     // External pnpm supply-chain quirk (pnpm >= 10.21, https://github.com/pnpm/pnpm/issues/8889):
     // when a consumer enables `trust-policy=no-downgrade` (off by default, but a
@@ -304,22 +321,36 @@ function generatePackageJson(choices) {
         // themeDark on CodeHighlightConfig, --shiki-light/--shiki-dark, #1067) plus
         // stricter build-start validation that rejects unknown theme names. next.48:
         // re-export @takazudo/zfb/config from the zfb-shim.d.ts type shim — type-only
-        // fix, additive. next.49 (current pin): client-router WebKit bfcache fix —
+        // fix, additive. next.49: client-router WebKit bfcache fix —
         // re-sync the history index + originalLocation on a bfcache restore so
         // browser Back after an SPA navigation returns to the previous page instead
-        // of skipping an entry — runtime-only bug fix, additive. A fresh scaffold
+        // of skipping an entry — runtime-only bug fix, additive. next.50 (current
+        // pin): client-router fix to commit the SPA history entry BEFORE the View
+        // Transition, so on WebKit/iOS a single browser Back after an SPA navigation
+        // creates a distinct history entry instead of falling off the site —
+        // runtime-only bug fix, additive. next.51 (current pin): additive public-API
+        // surface — VNode/VNodeArray/VNodeObject are now exported from
+        // "@takazudo/zfb" (#972) — plus removal of the no-op linkValidation.allowExternal
+        // knob (#925); both are non-breaking for a fresh scaffold. A fresh scaffold
         // sets no explicit codeHighlight.theme so the default still applies. No
         // consumer-facing / CLI breaking change.
-        "@takazudo/zfb": "0.1.0-next.49",
-        "@takazudo/zfb-runtime": "0.1.0-next.49",
+        "@takazudo/zfb": "0.1.0-next.51",
+        "@takazudo/zfb-runtime": "0.1.0-next.51",
         // zfb-adapter-cloudflare — required for any route with `prerender = false`.
         // Pinned in lockstep with @takazudo/zfb.
-        "@takazudo/zfb-adapter-cloudflare": "0.1.0-next.49",
+        "@takazudo/zfb-adapter-cloudflare": "0.1.0-next.51",
         // @takazudo/zudo-doc — published from this monorepo via
         // .github/workflows/publish-zudo-doc.yml. The pin here is bumped in
         // lockstep by scripts/release-create-zudo-doc.sh whenever zudo-doc's
         // version moves, so a fresh scaffold pulls the version we just published.
-        "@takazudo/zudo-doc": "^0.2.9",
+        // RELEASE DEPENDENCY (zudolab/zudo-doc#2188): the base template's
+        // global.css now `@import`s `@takazudo/zudo-doc/content.css`, an export
+        // added alongside this pin. The pinned range MUST resolve to a PUBLISHED
+        // version that ships that export — published 0.2.9 does NOT. check-pin-parity
+        // ties this pin to packages/zudo-doc's version, so the lockstep release
+        // bumps both together; do not cut a create-zudo-doc release until the
+        // matching @takazudo/zudo-doc version (with content.css) is on npm.
+        "@takazudo/zudo-doc": "^0.2.10",
         // zod — used by the generated zfb.config.ts. zfb-config-gen emits
         // `import { z } from "zod"` for the content-collection schema +
         // `z.toJSONSchema(...)` conversion. Without this dep, the consumer
@@ -374,7 +405,7 @@ function generatePackageJson(choices) {
         // @takazudo/zudo-doc/integrations/doc-history which in turn imports
         // @takazudo/zudo-doc-history-server/git-history. Without this dep the
         // plugin host fails at init with ERR_MODULE_NOT_FOUND — W8A (#1739).
-        deps["@takazudo/zudo-doc-history-server"] = "^0.2.9";
+        deps["@takazudo/zudo-doc-history-server"] = "^0.2.10";
         // W7A (#1736): doc-history-plugin.mjs spawns `tsx -e <inline-script>` to
         // run the v2 runtime in a TS-aware Node subprocess; without tsx the
         // plugin's preBuild step exits with ENOENT before zfb finishes config

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-zudo-doc",
-  "version": "0.2.9",
+  "version": "0.2.10",
   "description": "Create a new zudo-doc documentation site",
   "license": "MIT",
   "author": "Takeshi Takatsudo",

package/templates/base/pages/lib/_body-end-islands.tsx

@@ -35,6 +35,7 @@ import { settings } from "@/config/settings";
 import AiChatModal from "@/components/ai-chat-modal";
 import ClientRouterBootstrap from "@/components/client-router-bootstrap";
 import ImageEnlarge, { ImageEnlargeSsrFallback } from "@/components/image-enlarge";
+import MermaidEnlarge, { MermaidEnlargeSsrFallback } from "@/components/mermaid-enlarge";
 import { PageLoadingOverlay } from "@takazudo/zudo-doc/page-loading";
 // @slot:body-end-islands:imports
 
@@ -49,6 +50,7 @@ import { PageLoadingOverlay } from "@takazudo/zudo-doc/page-loading";
 (ClientRouterBootstrap as { displayName?: string }).displayName =
   "ClientRouterBootstrap";
 (ImageEnlarge as { displayName?: string }).displayName = "ImageEnlarge";
+(MermaidEnlarge as { displayName?: string }).displayName = "MermaidEnlarge";
 // @slot:body-end-islands:display-names
 
 /**
@@ -159,6 +161,20 @@ export function BodyEndIslands({
       }) as unknown as VNode)
     : null;
 
+  // Gated on `settings.mermaid`. Mirrors the imageEnlarge block: the SSR
+  // fallback is an empty, closed `<dialog class="zd-mermaid-dialog ...">` so
+  // the dist HTML carries one dialog from the start and hydration (when="idle")
+  // swaps in the real component. Unlike images (SSR-wrapped by the MDX paragraph
+  // override), mermaid renders client-side, so this island injects the enlarge
+  // button into each rendered diagram container itself.
+  const mermaidEnlarge = settings.mermaid
+    ? (Island({
+        when: "idle",
+        ssrFallback: <MermaidEnlargeSsrFallback />,
+        children: <MermaidEnlarge />,
+      }) as unknown as VNode)
+    : null;
+
   return (
     <>
       {/* Pure SSR — no Island wrap. The component emits its overlay div,
@@ -168,6 +184,7 @@ export function BodyEndIslands({
       {clientRouterBootstrap}
       {aiAssistant}
       {imageEnlarge}
+      {mermaidEnlarge}
       {/* @slot:body-end-islands:extra-islands */}
     </>
   );

package/templates/base/src/components/mermaid-enlarge.tsx

@@ -0,0 +1,490 @@
+"use client";
+
+// Mermaid-enlarge island — adds an "enlarge" affordance to client-rendered
+// mermaid diagrams plus a Google-Maps-style zoom/pan dialog.
+//
+// Unlike images (which the MDX paragraph override SSR-wraps in
+// `<figure class="zd-enlargeable">` with the enlarge button already in the
+// markup — see pages/_mdx-components.ts), mermaid diagrams render CLIENT-SIDE:
+// the mermaid init script (packages/zudo-doc/src/code-syntax/mermaid-init-script.ts)
+// imports mermaid from a CDN, runs `mermaid.run()`, then sets
+// `data-mermaid-rendered` on each `.mermaid` container and injects the `<svg>`.
+// So there is no server markup to wrap — this island must INJECT the enlarge
+// button into each diagram container after it renders.
+//
+// Lifecycle coupling with the mermaid init script:
+//   * Primary trigger: a MutationObserver on the content scope watching for the
+//     `data-mermaid-rendered` attribute appearing (and the `<svg>` child).
+//   * SPA hops: AFTER_NAVIGATE_EVENT re-scans the (swapped) content body.
+//   * Theme/tweak re-render: the init script's `reinitMermaid` REMOVES and
+//     regenerates the `<svg>` (debounced 300ms). The button lives on the
+//     `.mermaid` CONTAINER (which persists), and the dedupe guard is keyed by
+//     the container — so the button is neither dropped nor duplicated when the
+//     svg is regenerated. If the dialog is open during a re-render, the open
+//     diagram's fresh `<svg>` is re-cloned.
+
+// Use `preact/compat` so the bundle resolves to Preact's React-shim at runtime
+// (zfb's esbuild step doesn't alias bare `react` to `preact/compat`). Mirrors
+// image-enlarge.tsx.
+import type { JSX } from "preact";
+import { useState, useEffect, useRef, useCallback } from "preact/compat";
+import { AFTER_NAVIGATE_EVENT } from "@takazudo/zudo-doc/transitions";
+
+// ---------------------------------------------------------------------------
+// Shared dialog shell constants
+//
+// The hydrated component and the SSR fallback below render into the same Island
+// container, so they MUST agree on class string and inline style — otherwise
+// the dist HTML and the post-hydration DOM disagree and the first interaction
+// flashes. Sourcing both from the same constants closes that drift gap.
+//
+// The dialog itself is intentionally transform-FREE (centered via
+// position:fixed; inset:0; margin:auto). The zoom/pan transform lives on an
+// INNER wrapper — a transform on the `<dialog>` would establish a containing
+// block for its `position: fixed` descendants, re-anchoring the fixed close
+// button to the dialog corner instead of the viewport. Mirrors image-enlarge.
+//
+// z-modal / backdrop:z-modal-backdrop are defense-in-depth for the SPA-swap
+// window: a still-open showModal() dialog can lose top-layer promotion when the
+// page body is swapped, so the explicit modal-tier z-index keeps it above all
+// chrome. Intentionally redundant in the normal top-layer case.
+// ---------------------------------------------------------------------------
+const DIALOG_CLASS =
+  "zd-mermaid-dialog z-modal mx-auto h-[90vh] max-h-[90vh] w-[90vw] max-w-[90vw] overflow-hidden border border-muted bg-surface p-0 backdrop:z-modal-backdrop";
+const DIALOG_STYLE = {
+  position: "fixed",
+  inset: "0",
+  margin: "auto",
+} as const;
+
+// Selector for the content-scope root. The button injector scans within this
+// scope with `.querySelectorAll(".mermaid")` — no deeper constant needed.
+const CONTENT_SCOPE_SELECTOR = "main .zd-content";
+
+// The diagram svg is a DIRECT child of the `.mermaid` container; the injected
+// enlarge button's own icon svg is a grandchild. Selecting `:scope > svg` (not a
+// descendant `svg`) so we never pick up the button icon — which matters during a
+// theme/tweak re-render, when the diagram svg is briefly removed and a bare
+// `querySelector("svg")` would fall back to the button's icon.
+const DIAGRAM_SVG_SELECTOR = ":scope > svg";
+
+// Container-keyed dedupe marker. Set on the `.mermaid` container (which persists
+// across theme/tweak re-renders) once its enlarge button is injected, so the
+// re-render that regenerates the inner `<svg>` doesn't drop or duplicate it.
+const BTN_INJECTED_ATTR = "data-mermaid-enlarge-ready";
+
+// Zoom step + clamps. scale 1 = diagram fits the dialog (contain).
+const ZOOM_STEP = 1.25;
+const MIN_SCALE = 1;
+const MAX_SCALE = 4;
+
+// The enlarge button's 4-corner-arrows icon (same shape as ENLARGE_SVG in
+// pages/_mdx-components.ts) is injected as an innerHTML string in injectButton()
+// below — the button itself is created via document.createElement because the
+// mermaid container is plain DOM, not part of this island's render tree.
+
+// Toolbar icons. currentColor + aria-hidden so they inherit the toolbar button
+// color and are skipped by assistive tech (the buttons carry aria-labels).
+function PlusIcon() {
+  return (
+    <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" aria-hidden="true" focusable="false">
+      <line x1="12" y1="5" x2="12" y2="19" />
+      <line x1="5" y1="12" x2="19" y2="12" />
+    </svg>
+  );
+}
+
+function MinusIcon() {
+  return (
+    <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" aria-hidden="true" focusable="false">
+      <line x1="5" y1="12" x2="19" y2="12" />
+    </svg>
+  );
+}
+
+function PanIcon() {
+  return (
+    <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="1.6" strokeLinejoin="round" strokeLinecap="round" aria-hidden="true" focusable="false">
+      <path d="M9 11V5.5a1.5 1.5 0 0 1 3 0V11" />
+      <path d="M12 11V4.5a1.5 1.5 0 0 1 3 0V11" />
+      <path d="M15 11V6a1.5 1.5 0 0 1 3 0v6.5a6.5 6.5 0 0 1-6.5 6.5h-1a6 6 0 0 1-4.6-2.16l-2.2-2.86a1.5 1.5 0 0 1 2.3-1.92L9 13" />
+      <path d="M9 11V8a1.5 1.5 0 0 0-3 0v5" />
+    </svg>
+  );
+}
+
+interface OpenDiagram {
+  /** The live `.mermaid` container being shown — used to re-clone on re-render. */
+  container: HTMLElement;
+  /** The cloned `<svg>` outerHTML to render inside the pan viewport. */
+  svgHtml: string;
+}
+
+export default function MermaidEnlarge() {
+  const [open, setOpen] = useState<OpenDiagram | null>(null);
+
+  // Zoom/pan state. scale 1 = diagram fits the dialog (contain); translate 0,0.
+  const [scale, setScale] = useState(1);
+  const [translate, setTranslate] = useState({ x: 0, y: 0 });
+  const [panActive, setPanActive] = useState(false);
+
+  const dialogRef = useRef<HTMLDialogElement>(null);
+  const innerRef = useRef<HTMLDivElement>(null);
+  // Pointer-drag bookkeeping (refs so the handlers don't re-create on each move).
+  const dragState = useRef<{
+    dragging: boolean;
+    startX: number;
+    startY: number;
+    originX: number;
+    originY: number;
+  }>({ dragging: false, startX: 0, startY: 0, originX: 0, originY: 0 });
+
+  // -----------------------------------------------------------------------
+  // Button injection: scan the content scope, inject one enlarge button into
+  // each RENDERED diagram container, and add `.zd-mermaid-enlargeable` (which
+  // makes the container position:relative so the absolutely-positioned button
+  // anchors to it).
+  // -----------------------------------------------------------------------
+  useEffect(() => {
+    let mutationObserver: MutationObserver | null = null;
+
+    function injectButton(container: HTMLElement) {
+      // Container-keyed guard: the theme/tweak re-render regenerates the inner
+      // <svg> but the container (and this marker) persists.
+      if (container.hasAttribute(BTN_INJECTED_ATTR)) return;
+      // Only inject once the diagram has actually rendered — the button is
+      // meaningless before there's an <svg> to enlarge.
+      const rendered =
+        container.hasAttribute("data-mermaid-rendered") ||
+        container.querySelector(DIAGRAM_SVG_SELECTOR) !== null;
+      if (!rendered) return;
+
+      container.setAttribute(BTN_INJECTED_ATTR, "");
+      container.classList.add("zd-mermaid-enlargeable");
+
+      const btn = document.createElement("button");
+      btn.type = "button";
+      btn.className = "zd-enlarge-btn";
+      btn.setAttribute("aria-label", "Enlarge diagram");
+      // 4-corner-arrows icon (matches ENLARGE_SVG used by image-enlarge).
+      btn.innerHTML =
+        '<svg viewBox="0 0 38.99 38.99" fill="currentColor" focusable="false" aria-hidden="true">' +
+        '<polygon points="16.2 13.74 5.92 3.47 11.2 3.47 11.2 0 3.47 0 0 0 0 3.47 0 11.2 3.47 11.2 3.47 5.92 13.74 16.2 16.2 13.74" />' +
+        '<polygon points="25.24 16.2 35.52 5.92 35.52 11.2 38.99 11.2 38.99 3.47 38.99 0 35.52 0 27.79 0 27.79 3.47 33.07 3.47 22.79 13.74 25.24 16.2" />' +
+        '<polygon points="22.79 25.24 33.07 35.52 27.79 35.52 27.79 38.99 35.52 38.99 38.99 38.99 38.99 35.52 38.99 27.79 35.52 27.79 35.52 33.07 25.24 22.79 22.79 25.24" />' +
+        '<polygon points="13.74 22.79 3.47 33.07 3.47 27.79 0 27.79 0 35.52 0 38.99 3.47 38.99 11.2 38.99 11.2 35.52 5.92 35.52 16.2 25.24 13.74 22.79" />' +
+        "</svg>";
+      container.appendChild(btn);
+    }
+
+    function scan() {
+      const scope = document.querySelector(CONTENT_SCOPE_SELECTOR);
+      if (!scope) return;
+      scope
+        .querySelectorAll<HTMLElement>(".mermaid")
+        .forEach((el) => injectButton(el));
+    }
+
+    function startObserving() {
+      const scope = document.querySelector(CONTENT_SCOPE_SELECTOR);
+      if (scope) {
+        // Watch for: new `.mermaid` containers (childList), the
+        // `data-mermaid-rendered` attribute flipping on (attributes), and the
+        // svg child appearing (childList subtree). Any of these means a diagram
+        // is now eligible for the button.
+        mutationObserver = new MutationObserver(() => scan());
+        mutationObserver.observe(scope, {
+          childList: true,
+          subtree: true,
+          attributes: true,
+          attributeFilter: ["data-mermaid-rendered"],
+        });
+      }
+      scan();
+    }
+
+    function handleAfterNavigate() {
+      mutationObserver?.disconnect();
+      mutationObserver = null;
+      startObserving();
+    }
+
+    startObserving();
+    document.addEventListener(AFTER_NAVIGATE_EVENT, handleAfterNavigate);
+
+    return () => {
+      mutationObserver?.disconnect();
+      document.removeEventListener(AFTER_NAVIGATE_EVENT, handleAfterNavigate);
+    };
+  }, []);
+
+  // -----------------------------------------------------------------------
+  // Delegated open handler: a click on an injected `.zd-enlarge-btn` inside a
+  // `.zd-mermaid-enlargeable` clones that diagram's `<svg>` into the dialog.
+  // Mirrors image-enlarge's document-level delegated click.
+  // -----------------------------------------------------------------------
+  useEffect(() => {
+    function handleDocumentClick(e: MouseEvent) {
+      const target = e.target as Element;
+      const container = target.closest(".zd-mermaid-enlargeable") as HTMLElement | null;
+      if (!container) return;
+      if (!target.closest(".zd-enlarge-btn")) return;
+      const svg = container.querySelector(DIAGRAM_SVG_SELECTOR);
+      if (!svg) return;
+      // Reset zoom/pan on every open.
+      setScale(1);
+      setTranslate({ x: 0, y: 0 });
+      setPanActive(false);
+      setOpen({ container, svgHtml: svg.outerHTML });
+    }
+    document.addEventListener("click", handleDocumentClick);
+    return () => document.removeEventListener("click", handleDocumentClick);
+  }, []);
+
+  // -----------------------------------------------------------------------
+  // Re-clone the fresh `<svg>` if the underlying diagram re-renders while the
+  // dialog is open (theme/tweak flip removes & regenerates the svg).
+  // -----------------------------------------------------------------------
+  useEffect(() => {
+    if (!open) return;
+    const { container } = open;
+    const observer = new MutationObserver(() => {
+      const svg = container.querySelector(DIAGRAM_SVG_SELECTOR);
+      if (svg && svg.outerHTML !== open.svgHtml) {
+        setOpen({ container, svgHtml: svg.outerHTML });
+      }
+    });
+    observer.observe(container, { childList: true, subtree: true });
+    return () => observer.disconnect();
+  }, [open]);
+
+  const handleClose = useCallback(() => setOpen(null), []);
+
+  // -----------------------------------------------------------------------
+  // Dialog open/close sync (inlined from useModalDialog — template projects
+  // do not ship src/hooks/use-modal-dialog.ts, so the hook is not available).
+  // -----------------------------------------------------------------------
+  const isOpen = open !== null;
+
+  // Sync dialog open/close with state.
+  useEffect(() => {
+    const dialog = dialogRef.current;
+    if (!dialog) return;
+    if (isOpen && !dialog.open) {
+      dialog.showModal();
+    } else if (!isOpen && dialog.open) {
+      dialog.close();
+    }
+  }, [isOpen]);
+
+  // Fire handleClose when the dialog is closed natively (Escape key).
+  useEffect(() => {
+    const dialog = dialogRef.current;
+    if (!dialog) return;
+    function onDialogClose() {
+      if (isOpen) handleClose();
+    }
+    dialog.addEventListener("close", onDialogClose);
+    return () => dialog.removeEventListener("close", onDialogClose);
+  }, [isOpen, handleClose]);
+
+  // Close on SPA navigation when dialog is open.
+  useEffect(() => {
+    function handleNavigation() {
+      const dialog = dialogRef.current;
+      if (dialog?.open) {
+        dialog.close();
+        handleClose();
+      }
+    }
+    document.addEventListener(AFTER_NAVIGATE_EVENT, handleNavigation);
+    return () => document.removeEventListener(AFTER_NAVIGATE_EVENT, handleNavigation);
+  }, [handleClose]);
+
+  // Backdrop-click handler: close when the click target is the dialog itself.
+  // Preact-native event type so the template does not depend on @types/react
+  // being present in the scaffolded project.
+  function handleBackdropClick(e: JSX.TargetedMouseEvent<HTMLDialogElement>): void {
+    const dialog = dialogRef.current;
+    if (!dialog) return;
+    if (e.target === dialog) dialog.close();
+  }
+
+  // -----------------------------------------------------------------------
+  // Zoom controls
+  // -----------------------------------------------------------------------
+  const zoomIn = useCallback(() => {
+    setScale((s) => Math.min(MAX_SCALE, s * ZOOM_STEP));
+  }, []);
+
+  const zoomOut = useCallback(() => {
+    setScale((s) => {
+      const next = Math.max(MIN_SCALE, s / ZOOM_STEP);
+      // At full width, recenter (translate has no meaning when not zoomed in)
+      // and turn off pan mode.
+      if (next <= MIN_SCALE) {
+        setTranslate({ x: 0, y: 0 });
+        setPanActive(false);
+      }
+      return next;
+    });
+  }, []);
+
+  const togglePan = useCallback(() => {
+    setPanActive((p) => !p);
+  }, []);
+
+  // Clamp a candidate translate so the diagram can't be dragged fully
+  // offscreen — keep the scaled content overlapping the viewport. The max
+  // offset on each axis is half the overflow (scaled size minus base size).
+  const clampTranslate = useCallback(
+    (x: number, y: number, s: number) => {
+      const inner = innerRef.current;
+      if (!inner) return { x, y };
+      const rect = inner.getBoundingClientRect();
+      // rect already reflects the current transform; derive the un-scaled base
+      // from the applied scale so the bound is stable across repeated drags.
+      const baseW = rect.width / s;
+      const baseH = rect.height / s;
+      const maxX = Math.max(0, (baseW * s - baseW) / 2);
+      const maxY = Math.max(0, (baseH * s - baseH) / 2);
+      return {
+        x: Math.max(-maxX, Math.min(maxX, x)),
+        y: Math.max(-maxY, Math.min(maxY, y)),
+      };
+    },
+    [],
+  );
+
+  // -----------------------------------------------------------------------
+  // Pan drag (pointer events) — active only when pan mode is on and zoomed in.
+  // -----------------------------------------------------------------------
+  const onPointerDown = useCallback(
+    (e: PointerEvent) => {
+      if (!panActive || scale <= MIN_SCALE) return;
+      const d = dragState.current;
+      d.dragging = true;
+      d.startX = e.clientX;
+      d.startY = e.clientY;
+      d.originX = translate.x;
+      d.originY = translate.y;
+      (e.currentTarget as HTMLElement).setPointerCapture?.(e.pointerId);
+    },
+    [panActive, scale, translate],
+  );
+
+  const onPointerMove = useCallback(
+    (e: PointerEvent) => {
+      const d = dragState.current;
+      if (!d.dragging) return;
+      const nextX = d.originX + (e.clientX - d.startX);
+      const nextY = d.originY + (e.clientY - d.startY);
+      setTranslate(clampTranslate(nextX, nextY, scale));
+    },
+    [scale, clampTranslate],
+  );
+
+  const onPointerUp = useCallback((e: PointerEvent) => {
+    const d = dragState.current;
+    if (!d.dragging) return;
+    d.dragging = false;
+    (e.currentTarget as HTMLElement).releasePointerCapture?.(e.pointerId);
+  }, []);
+
+  const zoomed = scale > MIN_SCALE;
+  const atMax = scale >= MAX_SCALE;
+
+  return (
+    <dialog
+      ref={dialogRef}
+      onClick={handleBackdropClick}
+      aria-label="Enlarged diagram"
+      className={DIALOG_CLASS}
+      style={DIALOG_STYLE}
+    >
+      {open && (
+        <>
+          <div
+            className="zd-mermaid-viewport"
+            // Pointer handlers live on the viewport so a drag started anywhere
+            // over the diagram pans it. `touch-action: none` (in CSS) lets the
+            // pointer events fire on touch without the browser scrolling.
+            onPointerDown={onPointerDown}
+            onPointerMove={onPointerMove}
+            onPointerUp={onPointerUp}
+            onPointerCancel={onPointerUp}
+            data-pan-active={panActive && zoomed ? "" : undefined}
+          >
+            <div
+              ref={innerRef}
+              className="zd-mermaid-transform"
+              style={{
+                transform: `translate(${translate.x}px, ${translate.y}px) scale(${scale})`,
+                transformOrigin: "center",
+              }}
+              // The cloned mermaid svg is trusted markup produced by the local
+              // mermaid render; re-cloned here verbatim.
+              dangerouslySetInnerHTML={{ __html: open.svgHtml }}
+            />
+          </div>
+
+          <div className="zd-mermaid-toolbar" role="toolbar" aria-label="Diagram zoom controls">
+            <button
+              type="button"
+              className="zd-mermaid-tool-btn"
+              aria-label="Zoom in"
+              onClick={zoomIn}
+              disabled={atMax}
+            >
+              <PlusIcon />
+            </button>
+            <button
+              type="button"
+              className="zd-mermaid-tool-btn"
+              aria-label="Zoom out"
+              onClick={zoomOut}
+              disabled={!zoomed}
+            >
+              <MinusIcon />
+            </button>
+            <button
+              type="button"
+              className="zd-mermaid-tool-btn"
+              aria-label="Toggle pan mode"
+              aria-pressed={panActive}
+              onClick={togglePan}
+              disabled={!zoomed}
+            >
+              <PanIcon />
+            </button>
+          </div>
+
+          <button
+            type="button"
+            onClick={() => dialogRef.current?.close()}
+            className="zd-enlarge-dialog-close"
+            aria-label="Close enlarged diagram"
+          >
+            <svg viewBox="0 0 161.03 161.03" fill="currentColor" aria-hidden="true" focusable="false">
+              <polygon points="161.03 10.27 150.76 0 80.51 70.24 10.27 0 0 10.27 70.24 80.51 0 150.76 10.27 161.03 80.51 90.78 150.76 161.03 161.03 150.76 90.78 80.51 161.03 10.27" />
+            </svg>
+          </button>
+        </>
+      )}
+    </dialog>
+  );
+}
+
+/**
+ * Static SSR fallback for the {@link MermaidEnlarge} island.
+ *
+ * The body-end Island wrapper renders this on the server so the dist HTML
+ * carries an empty, closed `<dialog class="zd-mermaid-dialog ...">` even before
+ * hydration (a `<dialog>` without `open` is `display:none` per UA stylesheet).
+ * The classes and inline style come from the shared `DIALOG_CLASS` /
+ * `DIALOG_STYLE` constants so the SSR fallback cannot drift from the hydrated
+ * `<dialog>` above. Mirrors `ImageEnlargeSsrFallback`.
+ */
+export function MermaidEnlargeSsrFallback() {
+  return <dialog aria-label="Enlarged diagram" className={DIALOG_CLASS} style={DIALOG_STYLE} />;
+}

package/templates/base/src/styles/global.css

@@ -35,6 +35,14 @@
 
 @import "@takazudo/zudo-doc/safelist.css";
 
+/* Content typography (`.zd-content` rules + admonitions + mermaid layout).
+   Shipped by @takazudo/zudo-doc as the single source of truth — do not inline
+   these rules here (they used to live here and drifted; see
+   zudolab/zudo-doc#2188). The @layer zd-flow order it relies on is declared
+   above (line 11); the safelist import above generates the component utilities
+   its headings/links/etc. depend on. */
+@import "@takazudo/zudo-doc/content.css";
+
 /* ========================================
  * Tailwind v4 content sources
  *
@@ -290,410 +298,6 @@ body {
   }
 }
 
-/* ========================================
- * Content typography (.zd-content)
- *
- * Direct element styling — no prose plugin.
- * Uses :where() for zero specificity (easy to override).
- * Font size pattern inspired by zpaper: paired size + line-height.
- * ======================================== */
-
-.zd-content {
-  color: var(--color-fg);
-  font-size: var(--text-body);
-  line-height: var(--leading-relaxed);
-}
-
-/* ── Flow spacing (vertical rhythm) ── */
-
-/* In the `zd-flow` cascade layer (declared at the top of this file) so the
- * unlayered `tailwindcss/utilities` import wins over it: unlayered declarations
- * always beat layered ones regardless of specificity or source order. Both this
- * rule and a `mt-*` utility have specificity (0,1,0); without the layer this
- * rule comes later in source order and silently kills every `mt-*` on a
- * `.zd-content` direct child. zd-flow sits ABOVE zd-preflight so this rule still
- * beats preflight's `* { margin: 0 }` reset and the .zd-content rhythm is
- * preserved for plain content blocks. The layer is scoped to ONLY this flow rule
- * — every other `.zd-content` author rule (links, code, lists, headings, the
- * `:first-child` reset, etc.) stays unlayered so utilities do NOT flip those.
- * See zudolab/zudo-doc#2082 / #2109. */
-@layer zd-flow {
-  .zd-content > :where(* + *) {
-    margin-top: var(--flow-space, var(--spacing-vsp-md));
-  }
-}
-
-/* ── Headings ── */
-
-.zd-content :where(h2) {
-  font-size: var(--text-title);
-  font-weight: var(--font-weight-bold);
-  line-height: var(--leading-tight);
-  margin-top: var(--spacing-vsp-2xl);
-  margin-bottom: var(--spacing-vsp-xs);
-  padding-top: var(--spacing-vsp-sm);
-  border-top: 3px solid transparent;
-  border-image: linear-gradient(to right, var(--color-fg), transparent) 1;
-}
-
-.zd-content :where(h3) {
-  font-size: var(--text-body);
-  font-weight: var(--font-weight-bold);
-  line-height: var(--leading-snug);
-  margin-top: var(--spacing-vsp-xl);
-  margin-bottom: var(--spacing-vsp-xs);
-  padding-top: var(--spacing-vsp-xs);
-  border-top: 2px solid transparent;
-  border-image: linear-gradient(to right, var(--color-muted), transparent) 1;
-}
-
-.zd-content :where(h4) {
-  font-size: var(--text-body);
-  font-weight: var(--font-weight-semibold);
-  line-height: var(--leading-snug);
-  margin-top: var(--spacing-vsp-lg);
-  margin-bottom: var(--spacing-vsp-xs);
-  padding-top: var(--spacing-vsp-xs);
-  border-top: 1px solid transparent;
-  border-image: linear-gradient(to right, var(--color-muted), transparent) 1;
-}
-
-.zd-content :where(h5, h6) {
-  font-size: var(--text-small);
-  font-weight: var(--font-weight-semibold);
-  line-height: var(--leading-snug);
-  margin-top: var(--spacing-vsp-md);
-  margin-bottom: var(--spacing-vsp-2xs);
-}
-
-/* ── Heading auto-links ── */
-
-.zd-content :where(h2, h3, h4, h5, h6) .hash-link {
-  text-decoration: none;
-  margin-left: var(--spacing-hsp-sm);
-  opacity: 0;
-  transition: opacity 0.15s;
-}
-
-.zd-content :where(h2, h3, h4, h5, h6) .hash-link::after {
-  content: "#";
-  color: var(--color-accent);
-}
-
-.zd-content :where(h2, h3, h4, h5, h6):hover .hash-link {
-  opacity: 1;
-}
-
-.zd-content :where(h2, h3, h4, h5, h6) .hash-link:focus-visible {
-  opacity: 1;
-  outline: 2px solid var(--color-accent);
-  outline-offset: 2px;
-}
-
-/* Tighten spacing after headings */
-.zd-content :where(h2 + *, h3 + *, h4 + *, h5 + *, h6 + *) {
-  margin-top: 0;
-}
-
-/* ── Paragraphs ── */
-
-.zd-content :where(p) {
-  margin-top: 0;
-  margin-bottom: var(--spacing-vsp-md);
-}
-
-/* ── Links ── */
-
-.zd-content :where(a:not(.block):not([data-site-nav] *)) {
-  color: var(--color-accent);
-  text-decoration: underline;
-}
-
-.zd-content :where(a:not(.block):not([data-site-nav] *):hover) {
-  color: var(--color-accent-hover);
-}
-
-/* ── Bold / Strong ── */
-
-.zd-content :where(strong) {
-  font-weight: var(--font-weight-bold);
-  color: var(--color-fg);
-}
-
-/* ── Lists ── */
-
-.zd-content :where(ul) {
-  list-style-type: disc;
-  padding-left: var(--spacing-hsp-xl);
-  margin-bottom: var(--spacing-vsp-md);
-}
-
-.zd-content :where(ol) {
-  list-style-type: decimal;
-  padding-left: var(--spacing-hsp-xl);
-  margin-bottom: var(--spacing-vsp-md);
-}
-
-.zd-content :where(li) {
-  margin-bottom: var(--spacing-vsp-xs);
-}
-
-.zd-content :where(li::marker) {
-  color: var(--color-muted);
-}
-
-.zd-content :where(li > ul, li > ol) {
-  margin-top: var(--spacing-vsp-xs);
-  margin-bottom: 0;
-}
-
-/* ── Blockquotes ── */
-
-.zd-content :where(blockquote) {
-  border-left: 3px solid var(--color-muted);
-  padding-left: var(--spacing-hsp-lg);
-  color: var(--color-muted);
-  font-style: italic;
-  margin-bottom: var(--spacing-vsp-md);
-}
-
-.zd-content :where(blockquote p) {
-  margin-bottom: var(--spacing-vsp-xs);
-}
-
-/* ── Inline code ── */
-
-.zd-content :where(code:not(pre code)) {
-  font-size: var(--text-small);
-  font-weight: var(--font-weight-medium);
-  font-family: var(--font-mono);
-  background-color: var(--color-code-bg);
-  color: var(--color-code-fg);
-  border-radius: var(--radius-DEFAULT);
-  padding: 2px var(--spacing-hsp-xs);
-}
-
-/* ── Code blocks (pre) ── */
-
-.zd-content :where(pre) {
-  font-size: var(--text-small);
-  line-height: var(--leading-relaxed);
-  border: 1px solid var(--color-muted);
-  padding: var(--spacing-vsp-sm) var(--spacing-hsp-lg);
-  margin-bottom: var(--spacing-vsp-md);
-  overflow-x: auto;
-}
-
-.zd-content :where(pre code) {
-  background: transparent;
-  padding: 0;
-  border: none;
-  color: inherit;
-  font-size: inherit;
-}
-
-/* ── Tables ── */
-
-.zd-content :where(table) {
-  width: 100%;
-  border-collapse: collapse;
-  font-size: var(--text-small);
-  margin-bottom: var(--spacing-vsp-md);
-}
-
-.zd-content :where(th),
-.zd-content :where(td) {
-  padding: var(--spacing-vsp-xs) var(--spacing-hsp-md);
-  border-bottom: 1px solid var(--color-muted);
-  overflow-wrap: break-word;
-}
-
-.zd-content :where(th) {
-  font-weight: var(--font-weight-semibold);
-  text-align: left;
-  border-bottom-width: 2px;
-}
-
-/* ── Horizontal rules ── */
-
-.zd-content :where(hr) {
-  border: none;
-  border-top: 1px solid var(--color-muted);
-  margin: var(--spacing-vsp-xl) 0;
-}
-
-/* ── Images ── */
-
-.zd-content :where(img) {
-  max-width: 100%;
-  height: auto;
-}
-
-/* ── Definition lists ── */
-
-.zd-content :where(dt) {
-  font-weight: var(--font-weight-semibold);
-  margin-top: var(--spacing-vsp-md);
-}
-
-.zd-content :where(dd) {
-  padding-left: var(--spacing-hsp-xl);
-  margin-bottom: var(--spacing-vsp-xs);
-}
-
-/* ========================================
- * Admonitions ([data-admonition])
- *
- * Variant→color mapping: note→accent, tip→success, info→info,
- * warning→warning, danger→danger. Background tint uses
- * `color-mix(in srgb, var(--color-X) 12%, var(--color-bg))` for an opaque
- * per-theme tinted backdrop. Class names are dynamic (admonition-${variant})
- * so Tailwind cannot scan them; rules must live here explicitly.
- * See zudolab/zudo-doc#1357 / #1444 / #1456.
- * ======================================== */
-
-[data-admonition] {
-  border-left: 4px solid var(--color-muted);
-  /* Asymmetric padding mirrors the Astro reference: generous top, snug bottom. */
-  padding: var(--spacing-vsp-md) var(--spacing-hsp-lg) var(--spacing-vsp-2xs);
-  background-color: color-mix(in srgb, var(--color-muted) 12%, var(--color-bg));
-  border-radius: 0 var(--radius-DEFAULT) var(--radius-DEFAULT) 0;
-}
-
-.admonition-title {
-  font-weight: var(--font-weight-semibold);
-  font-size: var(--text-small);
-  margin-bottom: var(--spacing-vsp-2xs);
-}
-
-/* Variant icon — emoji rendered via ::before so the stub markup stays
- * variant-agnostic and the icon vocabulary lives next to its color rule. */
-.admonition-title::before {
-  margin-right: var(--spacing-hsp-2xs);
-}
-
-.admonition-body > :first-child {
-  margin-top: 0;
-}
-
-.admonition-body > :last-child {
-  margin-bottom: 0;
-}
-
-[data-admonition="note"],
-.admonition-note {
-  border-left-color: var(--color-accent);
-  background-color: color-mix(in srgb, var(--color-accent) 12%, var(--color-bg));
-}
-
-[data-admonition="note"] .admonition-title,
-.admonition-note .admonition-title {
-  color: var(--color-accent);
-}
-
-[data-admonition="note"] .admonition-title::before,
-.admonition-note .admonition-title::before {
-  content: "📝";
-}
-
-[data-admonition="tip"],
-.admonition-tip {
-  border-left-color: var(--color-success);
-  background-color: color-mix(in srgb, var(--color-success) 12%, var(--color-bg));
-}
-
-[data-admonition="tip"] .admonition-title,
-.admonition-tip .admonition-title {
-  color: var(--color-success);
-}
-
-[data-admonition="tip"] .admonition-title::before,
-.admonition-tip .admonition-title::before {
-  content: "💡";
-}
-
-[data-admonition="info"],
-.admonition-info {
-  border-left-color: var(--color-info);
-  background-color: color-mix(in srgb, var(--color-info) 12%, var(--color-bg));
-}
-
-[data-admonition="info"] .admonition-title,
-.admonition-info .admonition-title {
-  color: var(--color-info);
-}
-
-[data-admonition="info"] .admonition-title::before,
-.admonition-info .admonition-title::before {
-  content: "ℹ️";
-}
-
-[data-admonition="warning"],
-.admonition-warning {
-  border-left-color: var(--color-warning);
-  background-color: color-mix(in srgb, var(--color-warning) 12%, var(--color-bg));
-}
-
-[data-admonition="warning"] .admonition-title,
-.admonition-warning .admonition-title {
-  color: var(--color-warning);
-}
-
-[data-admonition="warning"] .admonition-title::before,
-.admonition-warning .admonition-title::before {
-  content: "⚠️";
-}
-
-[data-admonition="danger"],
-.admonition-danger {
-  border-left-color: var(--color-danger);
-  background-color: color-mix(in srgb, var(--color-danger) 12%, var(--color-bg));
-}
-
-[data-admonition="danger"] .admonition-title,
-.admonition-danger .admonition-title {
-  color: var(--color-danger);
-}
-
-[data-admonition="danger"] .admonition-title::before,
-.admonition-danger .admonition-title::before {
-  content: "🚨";
-}
-
-/* github-alerts [!IMPORTANT] → magenta/accent-adjacent (p5 = magenta palette slot) */
-[data-admonition="important"],
-.admonition-important {
-  border-left-color: var(--color-p5);
-  background-color: color-mix(in srgb, var(--color-p5) 12%, var(--color-bg));
-}
-
-[data-admonition="important"] .admonition-title,
-.admonition-important .admonition-title {
-  color: var(--color-p5);
-}
-
-[data-admonition="important"] .admonition-title::before,
-.admonition-important .admonition-title::before {
-  content: "❗";
-}
-
-/* github-alerts [!CAUTION] → danger-adjacent (high severity, distinct from danger/🚨) */
-[data-admonition="caution"],
-.admonition-caution {
-  border-left-color: var(--color-danger);
-  background-color: color-mix(in srgb, var(--color-danger) 12%, var(--color-bg));
-}
-
-[data-admonition="caution"] .admonition-title,
-.admonition-caution .admonition-title {
-  color: var(--color-danger);
-}
-
-[data-admonition="caution"] .admonition-title::before,
-.admonition-caution .admonition-title::before {
-  content: "⛔";
-}
-
 /* ========================================
  * Code block buttons (copy + word wrap)
  * ======================================== */
@@ -901,25 +505,6 @@ pre[class^="syntect-"] .line .highlighted-word {
   margin: 0;
 }
 
-/* ========================================
- * Mermaid diagrams
- * ======================================== */
-
-.zd-content .mermaid {
-  @apply my-vsp-lg flex justify-center;
-}
-
-.zd-content .mermaid svg {
-  max-width: 100%;
-  height: auto;
-  overflow: visible;
-}
-
-/* Prevent mermaid edge labels from clipping text (foreignObject uses overflow:hidden) */
-.zd-content .mermaid foreignObject {
-  overflow: visible;
-}
-
 /* KaTeX math equations */
 .katex {
   font-size: 1.1em;
@@ -1271,4 +856,145 @@ dialog.zd-enlarge-dialog::backdrop {
   }
 }
 
+/* ========================================
+ * Mermaid enlarge (.zd-mermaid-enlargeable) — issue #2176 / #2178
+ *
+ * Unlike images (SSR-wrapped in figure.zd-enlargeable), mermaid diagrams render
+ * client-side, so the mermaid-enlarge island injects the `.zd-enlarge-btn` into
+ * each rendered `.mermaid` container and adds `.zd-mermaid-enlargeable` (which
+ * makes the container position:relative so the button anchors to it). The
+ * button + close-button visuals are SHARED with image-enlarge above
+ * (`.zd-enlarge-btn`, `.zd-enlarge-dialog-close`).
+ * ======================================== */
+
+.zd-mermaid-enlargeable {
+  position: relative;
+  border: 1px solid transparent;
+  border-radius: var(--radius-DEFAULT);
+  transition: border-color var(--default-transition-duration);
+}
+
+/* The diagram is always enlargeable once the button is injected — show a subtle
+ * border affordance, accent on hover (mirrors the image-enlarge affordance). */
+.zd-mermaid-enlargeable:has(.zd-enlarge-btn) {
+  cursor: pointer;
+  border-color: var(--color-muted);
+}
+
+.zd-mermaid-enlargeable:has(.zd-enlarge-btn):hover {
+  border-color: var(--color-accent);
+}
+
+/* Zoom/pan dialog. The `<dialog>` stays transform-free (see DIALOG_STYLE in
+ * mermaid-enlarge.tsx); the transform lives on .zd-mermaid-transform. */
+dialog.zd-mermaid-dialog::backdrop {
+  background: color-mix(in oklch, var(--color-overlay) 80%, transparent);
+}
+
+/* Pan viewport — fills the dialog and clips the (possibly zoomed) diagram.
+ * touch-action:none so pointer-drag pans on touch without the browser
+ * intercepting the gesture for scrolling. */
+.zd-mermaid-viewport {
+  width: 100%;
+  height: 100%;
+  overflow: hidden;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  touch-action: none;
+}
+
+.zd-mermaid-viewport[data-pan-active] {
+  cursor: grab;
+}
+
+.zd-mermaid-viewport[data-pan-active]:active {
+  cursor: grabbing;
+}
+
+.zd-mermaid-transform {
+  width: 100%;
+  height: 100%;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  will-change: transform;
+}
+
+/* SVG sizing — fit the cloned mermaid svg inside the dialog like
+ * object-fit:contain. The svg fills the viewport box (100% x 100%) and its
+ * viewBox content is letterboxed/centered by the default
+ * preserveAspectRatio="xMidYMid meet". A TALL diagram (e.g. a state diagram) no
+ * longer gets forced to full dialog width with `height:auto` driving the height
+ * far past the viewport via its aspect ratio — it now shrinks to fit the height
+ * instead. max-width/max-height !important neutralize the inline px sizing
+ * mermaid bakes onto the svg (without it the diagram renders tiny). Scoped to
+ * .zd-mermaid-transform (the cloned-diagram wrapper) so it does NOT hit the
+ * toolbar / close-button icon svgs that also live inside the dialog. */
+.zd-mermaid-transform svg {
+  max-width: 100% !important;
+  max-height: 100% !important;
+  width: 100%;
+  height: 100%;
+}
+
+/* Edge labels (e.g. "Yes"/"No") render inside a tightly-sized <foreignObject>;
+ * when the cloned diagram is upscaled to fill the dialog, sub-pixel overflow
+ * makes the browser clip the last glyph at the foreignObject's right edge.
+ * Letting the foreignObject overflow render keeps the full label visible. */
+.zd-mermaid-transform svg foreignObject {
+  overflow: visible;
+}
+
+/* Toolbar — bottom-center pill of zoom/pan controls. */
+.zd-mermaid-toolbar {
+  position: absolute;
+  bottom: var(--spacing-image-overlay-inset);
+  left: 50%;
+  transform: translateX(-50%);
+  display: flex;
+  gap: var(--spacing-hsp-2xs);
+  padding: var(--spacing-hsp-2xs);
+  border: 1px solid var(--color-muted);
+  border-radius: var(--radius-DEFAULT);
+  background: color-mix(in oklch, var(--color-surface) 92%, transparent);
+  z-index: var(--z-index-local-2);
+}
+
+.zd-mermaid-tool-btn {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: var(--spacing-icon-lg);
+  height: var(--spacing-icon-lg);
+  padding: var(--spacing-vsp-2xs);
+  border: none;
+  border-radius: var(--radius-DEFAULT);
+  background: transparent;
+  color: var(--color-fg);
+  cursor: pointer;
+  transition:
+    background-color var(--default-transition-duration),
+    opacity var(--default-transition-duration);
+}
+
+.zd-mermaid-tool-btn:hover:not([disabled]) {
+  background: color-mix(in oklch, var(--color-muted) 25%, transparent);
+}
+
+.zd-mermaid-tool-btn[aria-pressed="true"] {
+  background: color-mix(in oklch, var(--color-accent) 30%, transparent);
+  color: var(--color-accent);
+}
+
+.zd-mermaid-tool-btn[disabled] {
+  opacity: 0.4;
+  cursor: default;
+}
+
+.zd-mermaid-tool-btn > svg {
+  width: var(--spacing-icon-md);
+  height: var(--spacing-icon-md);
+}
+
 /* @slot:global-css:feature-styles */