create-zudo-doc 0.2.8 → 0.2.10

package/dist/compose.d.ts

@@ -80,6 +80,12 @@ export declare function validateDependencies(features: FeatureDefinition[], allS
  *   `p:` map entry) when imageEnlarge is enabled.
  * - `pages/lib/_body-end-islands.tsx` — tauri.ts injects the FindInPageInit
  *   island (import, displayName, Island mount) when tauri is enabled.
+ *   design-token-panel.ts injects the DesignTokenPanelBootstrap island
+ *   (import, displayName, Island mount + toggle shim) when designTokenPanel
+ *   is enabled.
+ * - `src/config/settings-types.ts` — design-token-panel.ts injects the
+ *   `"design-token-panel"` member into `HeaderRightTriggerName` when the
+ *   feature is enabled (replace-range between the :start/:end anchors).
  */
 export declare const ANCHOR_FILES: string[];
 /**

package/dist/compose.js

@@ -166,11 +166,18 @@ export function validateDependencies(features, allSelectedNames) {
  *   `p:` map entry) when imageEnlarge is enabled.
  * - `pages/lib/_body-end-islands.tsx` — tauri.ts injects the FindInPageInit
  *   island (import, displayName, Island mount) when tauri is enabled.
+ *   design-token-panel.ts injects the DesignTokenPanelBootstrap island
+ *   (import, displayName, Island mount + toggle shim) when designTokenPanel
+ *   is enabled.
+ * - `src/config/settings-types.ts` — design-token-panel.ts injects the
+ *   `"design-token-panel"` member into `HeaderRightTriggerName` when the
+ *   feature is enabled (replace-range between the :start/:end anchors).
  */
 export const ANCHOR_FILES = [
     "src/styles/global.css",
     "pages/_mdx-components.ts",
     "pages/lib/_body-end-islands.tsx",
+    "src/config/settings-types.ts",
 ];
 /**
  * Main composition entry point. Orchestrates the full feature composition

package/dist/features/design-token-panel.d.ts

@@ -2,11 +2,13 @@ import type { FeatureModule } from "../compose.js";
 /**
  * Design-token-panel (zdtp) feature.
  *
- * Injects the zdtp CSS @import at `@slot:global-css:feature-styles` in
- * `src/styles/global.css`. The bootstrap is loaded by
- * `pages/lib/design-token-panel-bootstrap` as a side effect when the
- * feature is enabled, and the header trigger is rendered by
- * `pages/lib/_header-with-defaults.tsx` from the `settings.headerRightItems`
- * entry `{ type: "trigger", trigger: "design-token-panel" }`.
+ * Injects:
+ * 1. The zdtp CSS @import at `@slot:global-css:feature-styles` in
+ *    `src/styles/global.css`.
+ * 2. The DesignTokenPanelBootstrap import, displayName, and Island mount
+ *    (with pre-hydration toggle shim) into
+ *    `pages/lib/_body-end-islands.tsx` via the three @slot: anchors
+ *    (imports / display-names / extra-islands). Mirrors the tauri feature
+ *    injection shape (zudolab/zudo-doc#2162).
  */
 export declare const designTokenPanelFeature: FeatureModule;

package/dist/features/design-token-panel.js

@@ -1,12 +1,38 @@
+/**
+ * Pre-hydration toggle shim for the zdtp panel (inline, minified).
+ *
+ * Emitted as a <script dangerouslySetInnerHTML> alongside the
+ * DesignTokenPanelBootstrap Island so the header palette button is
+ * responsive before the island hydrates. Records the first click as a
+ * boolean flag and exposes window.__zdtpReadyClicks so the bootstrap
+ * module can drain and re-dispatch once the real zdtp listener is live.
+ * Guards against double-installation across SPA body swaps via
+ * __zdtpToggleShimInstalled. Mirrors the host's ZDTP_TOGGLE_SHIM_SRC
+ * constant (pages/lib/_body-end-islands.tsx, zudolab/zudo-doc#1627 Part B).
+ */
+const ZDTP_TOGGLE_SHIM_SRC = `(function(){
+if(window.__zdtpToggleShimInstalled)return;
+window.__zdtpToggleShimInstalled=true;
+var pending=false;
+function shim(){pending=true;}
+window.addEventListener('toggle-design-token-panel',shim);
+window.__zdtpReadyClicks=function(){
+window.removeEventListener('toggle-design-token-panel',shim);
+delete window.__zdtpReadyClicks;
+if(pending){pending=false;window.dispatchEvent(new CustomEvent('toggle-design-token-panel'));}
+};
+})();`;
 /**
  * Design-token-panel (zdtp) feature.
  *
- * Injects the zdtp CSS @import at `@slot:global-css:feature-styles` in
- * `src/styles/global.css`. The bootstrap is loaded by
- * `pages/lib/design-token-panel-bootstrap` as a side effect when the
- * feature is enabled, and the header trigger is rendered by
- * `pages/lib/_header-with-defaults.tsx` from the `settings.headerRightItems`
- * entry `{ type: "trigger", trigger: "design-token-panel" }`.
+ * Injects:
+ * 1. The zdtp CSS @import at `@slot:global-css:feature-styles` in
+ *    `src/styles/global.css`.
+ * 2. The DesignTokenPanelBootstrap import, displayName, and Island mount
+ *    (with pre-hydration toggle shim) into
+ *    `pages/lib/_body-end-islands.tsx` via the three @slot: anchors
+ *    (imports / display-names / extra-islands). Mirrors the tauri feature
+ *    injection shape (zudolab/zudo-doc#2162).
  */
 export const designTokenPanelFeature = () => ({
     name: "designTokenPanel",
@@ -21,5 +47,54 @@ export const designTokenPanelFeature = () => ({
             anchor: "/* @slot:global-css:feature-styles */",
             content: `@import "@takazudo/zdtp/styles.css";`,
         },
+        // 1. Import the island entry. Inserted AFTER the
+        //    `// @slot:body-end-islands:imports` anchor.
+        {
+            file: "pages/lib/_body-end-islands.tsx",
+            anchor: "// @slot:body-end-islands:imports",
+            position: "after",
+            content: `import DesignTokenPanelBootstrap from "@/components/design-token-panel-bootstrap";`,
+        },
+        // 2. Stable island marker name (belt-and-braces guard matching the
+        //    sibling islands in the file). Inserted AFTER the
+        //    `// @slot:body-end-islands:display-names` anchor.
+        {
+            file: "pages/lib/_body-end-islands.tsx",
+            anchor: "// @slot:body-end-islands:display-names",
+            position: "after",
+            content: `(DesignTokenPanelBootstrap as { displayName?: string }).displayName = "DesignTokenPanelBootstrap";`,
+        },
+        // 4. Extend HeaderRightTriggerName with "design-token-panel". Uses
+        //    replace-range between the :start/:end anchors in settings-types.ts
+        //    so the base template emits only "ai-chat" and this injection adds
+        //    the zdtp trigger only when the feature is on (zudolab/zudo-doc#2162).
+        {
+            file: "src/config/settings-types.ts",
+            anchor: "// @slot:settings-types:trigger-names:start",
+            position: "replace",
+            content: `export type HeaderRightTriggerName = "design-token-panel" | "ai-chat";`,
+        },
+        // 3. Island mount + pre-hydration toggle shim. Inserted AFTER the
+        //    `{/* @slot:body-end-islands:extra-islands */}` anchor.
+        //    when="load" (not "idle"): the bootstrap module registers the
+        //    `toggle-design-token-panel` window listener as a side effect of
+        //    its import, so it must hydrate as early as possible (zudolab/zudo-doc#1623).
+        //    The inline <script> is the pre-hydration shim (zudolab/zudo-doc#1627 Part B).
+        {
+            file: "pages/lib/_body-end-islands.tsx",
+            anchor: "{/* @slot:body-end-islands:extra-islands */}",
+            position: "after",
+            content: `      {/* zdtp panel bootstrap: hydrates on load so configurePanel() runs early
+          and the toggle-design-token-panel listener is live before the user
+          clicks the header trigger. The inline script is the pre-hydration
+          shim that queues the first click (zudolab/zudo-doc#1627 Part B). */}
+      <script
+        dangerouslySetInnerHTML={{ __html: ${JSON.stringify(ZDTP_TOGGLE_SHIM_SRC)} }}
+      />
+      {Island({
+        when: "load",
+        children: <DesignTokenPanelBootstrap />,
+      }) as unknown as VNode}`,
+        },
     ],
 });

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,34 @@ 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
+    // common hardened posture), `pnpm install` aborts with ERR_PNPM_TRUST_DOWNGRADE
+    // on undici-types@6.21.0 — a transitive dep of @types/node@^22 whose earlier
+    // releases carried provenance attestation that 6.21.0 dropped. The package is a
+    // type-only stub and safe; this narrow exclusion lets a fresh scaffold install
+    // under a strict trust policy without disabling the guard wholesale. Pinned to
+    // the exact known-safe version so a future undici-types bump is re-reviewed.
+    await fs.outputFile(path.join(targetDir, ".npmrc"), "trust-policy-exclude[]=undici-types@6.21.0\n");
     const claudeContent = generateCLAUDEFile(choices);
     await fs.outputFile(path.join(targetDir, "CLAUDE.md"), claudeContent);
     // 4. Compose features (copy feature files + inject into shared files)
@@ -290,21 +317,40 @@ function generatePackageJson(choices) {
         // extraWatchPaths rebuilds, and TS-config-loader path canonicalization
         // (Takazudo/zudo-front-builder#1036–#1043). next.45: docs-only. next.46:
         // opt-in dev boot-lazy mode (#1057) + client-router timer lifecycle fixes —
-        // dev-server-only. next.47 (current pin): dual light/dark syntect themes
-        // (themeLight/themeDark on CodeHighlightConfig, --shiki-light/--shiki-dark,
-        // #1067) plus stricter build-start validation that rejects unknown theme
-        // names — additive; 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.47",
-        "@takazudo/zfb-runtime": "0.1.0-next.47",
+        // dev-server-only. next.47: dual light/dark syntect themes (themeLight/
+        // 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: 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. 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.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.47",
+        "@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.8",
+        // 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
@@ -359,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.8";
+        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/dist/settings-gen.js

@@ -259,10 +259,17 @@ export function generateSettingsFile(choices) {
     if (choices.headerRightItems !== undefined) {
         // User-supplied override (including empty array): emit each entry verbatim,
         // in the chosen order. An empty array means "no header-right items" — honor it.
-        // filterHeaderRightItems (src/utils/header-right-items.ts) handles runtime
-        // hiding of items whose feature is disabled — no need to gate emission
-        // here on choices.features.
+        // DEFENSIVE STRIP: drop any "design-token-panel" trigger when the
+        // designTokenPanel feature is off — the type "design-token-panel" is absent
+        // from HeaderRightTriggerName in a feature-off scaffold (gated via
+        // @slot:settings-types:trigger-names), so emitting it would cause a TS error
+        // (zudolab/zudo-doc#2162).
         for (const item of choices.headerRightItems) {
+            if (item.type === "trigger" &&
+                item.trigger === "design-token-panel" &&
+                !choices.features.includes("designTokenPanel")) {
+                continue;
+            }
             if (item.type === "trigger") {
                 lines.push(`    { type: "trigger", trigger: ${JSON.stringify(item.trigger)} },`);
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-zudo-doc",
-  "version": "0.2.8",
+  "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

@@ -34,8 +34,8 @@ import { settings } from "@/config/settings";
 
 import AiChatModal from "@/components/ai-chat-modal";
 import ClientRouterBootstrap from "@/components/client-router-bootstrap";
-import DesignTokenPanelBootstrap from "@/components/design-token-panel-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,9 +49,8 @@ import { PageLoadingOverlay } from "@takazudo/zudo-doc/page-loading";
 (AiChatModal as { displayName?: string }).displayName = "AiChatModal";
 (ClientRouterBootstrap as { displayName?: string }).displayName =
   "ClientRouterBootstrap";
-(DesignTokenPanelBootstrap as { displayName?: string }).displayName =
-  "DesignTokenPanelBootstrap";
 (ImageEnlarge as { displayName?: string }).displayName = "ImageEnlarge";
+(MermaidEnlarge as { displayName?: string }).displayName = "MermaidEnlarge";
 // @slot:body-end-islands:display-names
 
 /**
@@ -64,37 +63,6 @@ import { PageLoadingOverlay } from "@takazudo/zudo-doc/page-loading";
  */
 const DEFAULT_AI_CHAT_BODY_LABEL = "Ask a question about the documentation.";
 
-/**
- * SSR-emitted inline script that acts as a pre-hydration shim for the
- * `toggle-design-token-panel` window event. Because the
- * DesignTokenPanelBootstrap Island is deferred, zdtp's real
- * `toggle-design-token-panel` listener (registered in index.tsx at
- * module init) is not yet installed when the user clicks the header
- * palette button. This shim:
- *
- *  1. Records the first (and only meaningful) click as a boolean flag.
- *  2. Exposes `window.__zdtpReadyClicks` so the bootstrap Island can
- *     drain the queue and re-dispatch a single event once the real
- *     listener is live.
- *  3. Guards against double-installation across any re-evaluation path
- *     (SPA body swap, HMR, etc.) via `__zdtpToggleShimInstalled`.
- *
- * A single boolean (not an array) is used because the panel is a toggle —
- * any number of pre-hydration clicks should result in at most one open.
- */
-const ZDTP_TOGGLE_SHIM_SRC = `(function(){
-if(window.__zdtpToggleShimInstalled)return;
-window.__zdtpToggleShimInstalled=true;
-var pending=false;
-function shim(){pending=true;}
-window.addEventListener('toggle-design-token-panel',shim);
-window.__zdtpReadyClicks=function(){
-window.removeEventListener('toggle-design-token-panel',shim);
-delete window.__zdtpReadyClicks;
-if(pending){pending=false;window.dispatchEvent(new CustomEvent('toggle-design-token-panel'));}
-};
-})();`;
-
 /** Props for {@link BodyEndIslands}. */
 export interface BodyEndIslandsProps {
   /** Base path the AI chat modal uses to construct API URLs. */
@@ -109,15 +77,18 @@ export interface BodyEndIslandsProps {
 }
 
 /**
- * The default body-end islands a doc page may mount: the design-token
- * tweak panel (overlay, fixed-position), the AI chat modal (`<dialog>`
- * overlay), and the image-enlarge dialog (mounted lazily based on
- * viewport scan). Each is feature-gated — the design-token panel on
- * `settings.designTokenPanel`, the AI chat modal (and its sr-only
- * landmark heading) on `settings.aiAssistant`, and image-enlarge on
- * `settings.imageEnlarge` — so a feature-off consumer ships neither the
+ * The default body-end islands a doc page may mount: the AI chat modal
+ * (`<dialog>` overlay) and the image-enlarge dialog (mounted lazily based
+ * on viewport scan). Each is feature-gated — the AI chat modal (and its
+ * sr-only landmark heading) on `settings.aiAssistant`, and image-enlarge
+ * on `settings.imageEnlarge` — so a feature-off consumer ships neither the
  * island marker nor a misleading landmark (zudolab/zudo-doc#2058).
  *
+ * Optional feature islands (e.g. the design token panel bootstrap) are not
+ * listed here: they are injected at the body-end-islands composition
+ * anchors only when their feature is selected, so a feature-off scaffold
+ * carries no trace of them.
+ *
  * Each island is wrapped in `<Island ssrFallback>` so the heavy
  * component is NOT evaluated server-side — they depend on
  * `dialog.showModal()`, `localStorage`, `ResizeObserver`, runtime
@@ -143,37 +114,12 @@ export function BodyEndIslands({
     children: <ClientRouterBootstrap />,
   }) as unknown as VNode;
 
-  // Hydrates on load so configurePanel() runs as early as possible and
-  // the `toggle-design-token-panel` window listener is registered before
-  // the user can click the header trigger. Renders nothing visually —
-  // the zdtp panel self-mounts as a side-effect (zudolab/zudo-doc#1623).
-  //
-  // The inline <script> emitted alongside the Island is the pre-hydration
-  // toggle shim (zudolab/zudo-doc#1627 Part B). It captures the first
-  // click as a boolean flag and exposes window.__zdtpReadyClicks so the
-  // bootstrap module can drain and re-dispatch once the real zdtp listener
-  // is registered. Mirrors the PageLoadingOverlay SSR-script pattern.
-  const designTokenPanelBootstrap =
-    settings.designTokenPanel
-      ? (
-          <>
-            <script
-              dangerouslySetInnerHTML={{ __html: ZDTP_TOGGLE_SHIM_SRC }}
-            />
-            {Island({
-              when: "load",
-              children: <DesignTokenPanelBootstrap />,
-            }) as unknown as VNode}
-          </>
-        )
-      : null;
-
   // Gated on `settings.aiAssistant` (zudolab/zudo-doc#2058): when the AI
   // assistant feature is off, neither the AiChatModal island marker nor the
   // sr-only "AI Assistant" landmark heading should reach the SSG output —
   // otherwise feature-off consumers ship a dead island marker plus a
   // misleading screen-reader landmark for a section that never hydrates.
-  // Mirrors the `designTokenPanel` gating above.
+  // Same feature-gating pattern as the other optional body-end islands.
   //
   // KNOWN CAVEAT: zfb's island scanner walks the static `"use client"`
   // import chain, so gating this JSX removes the SSR marker and heading but
@@ -215,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,
@@ -222,9 +182,9 @@ export function BodyEndIslands({
           zfb:before-preparation / zfb:after-swap listeners at runtime. */}
       <PageLoadingOverlay />
       {clientRouterBootstrap}
-      {designTokenPanelBootstrap}
       {aiAssistant}
       {imageEnlarge}
+      {mermaidEnlarge}
       {/* @slot:body-end-islands:extra-islands */}
     </>
   );