create-zudo-doc 0.2.5 → 0.2.7

package/dist/features/claude-resources.js

@@ -1,6 +1,9 @@
 export const claudeResourcesFeature = () => ({
     name: "claudeResources",
     injections: [
-    // Plugin entry is handled by zfb-config-gen.ts — no shared file injection needed
+    // No shared file injection needed — this feature's touch points are:
+    //   - plugin entry: zfb-config-gen.ts (claudeResources conditional import/plugin)
+    //   - settings: settings-gen.ts (claudeResources object + defaultLocaleOnlyPrefixes array)
+    //   - devDep: scaffold.ts (tsx devDep — same subprocess runner as docHistory)
     ],
 });

package/dist/scaffold.js

@@ -277,7 +277,7 @@ function generatePackageJson(choices) {
         // pages render on first request instead of on every file-change tick
         // (Takazudo/zudo-front-builder#1029); `ZFB_DEV_EAGER=1` restores eager
         // mode. Dev-server-only change, no build/config migration needed.
-        // next.41 (current pin) adds a URL-space fallback in resolve_links —
+        // next.41 adds a URL-space fallback in resolve_links —
         // dir-style hrefs written from non-index pages now resolve against the
         // page's URL directory when the file-space lookup misses
         // (Takazudo/zudo-front-builder#1030) — and the data-file skip warning
@@ -285,16 +285,26 @@ function generatePackageJson(choices) {
         // include/exclude globs (#1032). No consumer-facing breaking change.
         // next.42/next.43: release-tooling + formatter-glob fixes only (npm-publish
         // idempotency, gitignored-artifact excludes). No consumer-facing change.
-        "@takazudo/zfb": "0.1.0-next.43",
-        "@takazudo/zfb-runtime": "0.1.0-next.43",
+        // next.44: embed-as-library enhancements only — ServerBuilder::with_page_cache
+        // for live content, an opt-in ExternalInvalidationHook to narrow
+        // 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",
         // zfb-adapter-cloudflare — required for any route with `prerender = false`.
         // Pinned in lockstep with @takazudo/zfb.
-        "@takazudo/zfb-adapter-cloudflare": "0.1.0-next.43",
+        "@takazudo/zfb-adapter-cloudflare": "0.1.0-next.47",
         // @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.5",
+        "@takazudo/zudo-doc": "^0.2.7",
         // 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
@@ -306,6 +316,7 @@ function generatePackageJson(choices) {
         // ^10.29.1 floor satisfies @takazudo/zdtp's preact peer range so the app
         // and zdtp resolve a single preact instance — a lower floor can split into
         // two copies and crash hook-using SSR islands with "undefined reading __H".
+        // See the designTokenPanel dep block below (~line 443) for the coupling.
         preact: "^10.29.1",
         // preact-render-to-string — zfb's emitted entry.mjs imports
         // `renderToString` from this package as `__zfb_renderToString` to
@@ -348,7 +359,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.5";
+        deps["@takazudo/zudo-doc-history-server"] = "^0.2.7";
         // 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
@@ -362,6 +373,8 @@ function generatePackageJson(choices) {
         devDeps["tsx"] = "^4.21.0";
     }
     if (choices.features.includes("designTokenPanel")) {
+        // @takazudo/zdtp requires preact >= 10.29.1 — see the preact floor comment
+        // above (~line 382) for why the floor is set there and the coupling this creates.
         deps["@takazudo/zdtp"] = "0.2.0-next.2";
     }
     if (choices.features.includes("tagGovernance")) {
@@ -386,6 +399,12 @@ function generatePackageJson(choices) {
         // the pages/lib call sites, so emitting the script would fail on a fresh
         // scaffold. Revisit once the template stubs carry typed props.
         "check:html": "html-validate \"dist/**/*.html\"",
+        // Z-index token codegen (#2148): regenerate the GENERATED:Z_INDEX @theme
+        // block in src/styles/global.css from src/config/z-index-tokens.ts, and a
+        // drift check for pre-push/CI. Both ship in base — the z-index token system
+        // is part of every scaffold.
+        "gen:z-index": "node scripts/gen-z-index.mjs",
+        "check:z-index": "node scripts/gen-z-index.mjs --check",
     };
     if (choices.features.includes("tagGovernance")) {
         scripts["tags:audit"] = "tsx scripts/tags-audit.ts";

package/dist/settings-gen.js

@@ -8,10 +8,10 @@ export function generateSettingsFile(choices) {
     lines.push(`  HeaderRightItem,`);
     lines.push(`  ColorModeConfig,`);
     lines.push(`  HtmlPreviewConfig,`);
-    lines.push(`  FrontmatterPreviewConfig,`);
     lines.push(`  LocaleConfig,`);
     lines.push(`  VersionConfig,`);
     lines.push(`  FooterConfig,`);
+    lines.push(`  FrontmatterPreviewConfig,`);
     lines.push(`  BodyFootUtilAreaConfig,`);
     lines.push(`  TagPlacement,`);
     lines.push(`  TagGovernanceMode,`);
@@ -23,10 +23,10 @@ export function generateSettingsFile(choices) {
     lines.push(`  HeaderRightItem,`);
     lines.push(`  ColorModeConfig,`);
     lines.push(`  HtmlPreviewConfig,`);
-    lines.push(`  FrontmatterPreviewConfig,`);
     lines.push(`  LocaleConfig,`);
     lines.push(`  VersionConfig,`);
     lines.push(`  FooterConfig,`);
+    lines.push(`  FrontmatterPreviewConfig,`);
     lines.push(`  BodyFootUtilAreaConfig,`);
     lines.push(`  TagPlacement,`);
     lines.push(`  TagGovernanceMode,`);
@@ -121,6 +121,8 @@ export function generateSettingsFile(choices) {
         lines.push(`  tagGovernance: "off" as TagGovernanceMode,`);
         lines.push(`  tagVocabulary: false as boolean,`);
     }
+    // Default false — fresh scaffolds typically don't need live frontmatter preview;
+    // users opt in once they're ready to wire up the preview panel.
     lines.push(`  frontmatterPreview: false as FrontmatterPreviewConfig | false,`);
     if (choices.features.includes("llmsTxt")) {
         lines.push(`  llmsTxt: true,`);
@@ -279,6 +281,9 @@ export function generateSettingsFile(choices) {
         }
         lines.push(`    { type: "component", component: "github-link" },`);
         lines.push(`    { type: "component", component: "theme-toggle" },`);
+        if (choices.features.includes("search")) {
+            lines.push(`    { type: "component", component: "search" },`);
+        }
         if (choices.features.includes("i18n")) {
             lines.push(`    { type: "component", component: "language-switcher" },`);
         }

package/package.json

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

package/templates/base/pages/lib/_search-widget-script.ts

@@ -24,6 +24,19 @@ export const SEARCH_WIDGET_SCRIPT = /* javascript */ `(function () {
 
   var PAGE_SIZE = 10;
 
+  // Allowlist-based href sanitizer: only relative paths and http(s) URLs are
+  // permitted. Anything else (e.g. javascript:, data:) falls back to "#" so a
+  // malicious entry in search-index.json cannot turn a result link into a
+  // script-injection vector.
+  function safeHref(url) {
+    if (!url) return "#";
+    var s = String(url);
+    if (s.startsWith("/") || s.startsWith("http://") || s.startsWith("https://")) {
+      return s;
+    }
+    return "#";
+  }
+
   function escapeHtml(text) {
     return String(text)
       .replace(/&/g, "&")
@@ -122,6 +135,10 @@ export const SEARCH_WIDGET_SCRIPT = /* javascript */ `(function () {
       this._shortcut = "";
       this._resultCountTemplate = "";
       this._keydownHandler = null;
+      // Delegated click handler on the results container: closing the dialog
+      // when a result link is activated (epic #2148). Held so disconnectedCallback
+      // can detach it on body swap.
+      this._resultsClickHandler = null;
       this._observer = null;
       this._sentinel = null;
       this._isLoadingBatch = false;
@@ -178,6 +195,24 @@ export const SEARCH_WIDGET_SCRIPT = /* javascript */ `(function () {
         this._input.addEventListener("input", function() { self.handleInput(); });
       }
 
+      // Close-on-result-click (epic #2148): result links are created dynamically
+      // in renderResult(), so use one delegated listener on the results container
+      // instead of per-link handlers. We do NOT preventDefault — the link's own
+      // navigation (zfb Strategy-B SPA swap or a plain load) must still proceed;
+      // we only close the <dialog> so it does not linger over the swapped page.
+      // closeDialog() runs synchronously before navigation; the dialog's close
+      // restores documentElement overflow via the existing "close" listener.
+      if (this._results) {
+        this._resultsClickHandler = function(e) {
+          var t = e.target;
+          while (t && t !== self._results) {
+            if (t.tagName === "A") { self.closeDialog(); return; }
+            t = t.parentNode;
+          }
+        };
+        this._results.addEventListener("click", this._resultsClickHandler);
+      }
+
       // Global keyboard shortcut (⌘K / Ctrl+K to open)
       this._keydownHandler = function(e) {
         if ((e.metaKey || e.ctrlKey) && e.key === "k") {
@@ -192,6 +227,11 @@ export const SEARCH_WIDGET_SCRIPT = /* javascript */ `(function () {
       // body swap when this element is NOT persisted via
       // data-zfb-transition-persist (zudolab/zudo-doc#1523).
       this._afterNavHandler = function() {
+        // Backstop for the original bug (epic #2148): if the dialog is somehow
+        // still open after an SPA body swap (e.g. a nav path that bypassed the
+        // result-click handler), close it so it does not linger / flash over the
+        // newly-swapped page. Safe no-op when already closed.
+        if (self._dialog && self._dialog.open) self.closeDialog();
         var kbdEl2 = self.querySelector("[data-kbd-shortcut]");
         if (kbdEl2) kbdEl2.textContent = self._shortcut;
       };
@@ -207,6 +247,10 @@ export const SEARCH_WIDGET_SCRIPT = /* javascript */ `(function () {
         document.removeEventListener(${JSON.stringify(AFTER_NAVIGATE_EVENT)}, this._afterNavHandler);
         this._afterNavHandler = null;
       }
+      if (this._resultsClickHandler && this._results) {
+        this._results.removeEventListener("click", this._resultsClickHandler);
+        this._resultsClickHandler = null;
+      }
       this.teardownSentinel();
     }
 
@@ -401,7 +445,7 @@ export const SEARCH_WIDGET_SCRIPT = /* javascript */ `(function () {
       var article = document.createElement("article");
       article.className = "-mx-hsp-lg border-b border-muted";
       var link = document.createElement("a");
-      link.href = entry.url || "#";
+      link.href = safeHref(entry.url);
       link.className =
         "group block px-hsp-lg py-vsp-sm focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-accent";
       var title = document.createElement("span");

package/templates/base/pages/lib/_search-widget.tsx

@@ -88,9 +88,17 @@ export function SearchWidget(props: SearchWidgetProps): JSX.Element {
             static HTML for no-JS users and crawlers. The browser treats
             it as a closed <dialog> until the custom element calls
             showModal(). */}
+        {/* z-modal / backdrop:z-modal-backdrop are defense-in-depth for the
+            SPA-swap window (zfb Strategy-B `zfb:after-swap`): a native
+            showModal() dialog normally sits in the top layer, but if it is
+            still open while the page body is swapped it can lose top-layer
+            promotion and fall back to z-index:auto, flashing behind the
+            header/sidebar. The explicit modal-tier z-index keeps it above all
+            chrome during that window. Intentionally redundant in the normal
+            (top-layer) case — do not remove as "redundant" (epic #2148). */}
         <dialog
           data-search-dialog
-          class="m-0 h-full w-full max-w-none border-none bg-transparent p-0 backdrop:bg-overlay/60 sm:mx-auto sm:my-[10vh] sm:h-auto sm:max-h-[80vh] sm:max-w-[52rem] sm:rounded-lg"
+          class="z-modal m-0 h-full w-full max-w-none border-none bg-transparent p-0 backdrop:z-modal-backdrop backdrop:bg-overlay/60 sm:mx-auto sm:my-[10vh] sm:h-auto sm:max-h-[80vh] sm:max-w-[52rem] sm:rounded-lg"
         >
           <div class="flex h-full flex-col overflow-hidden bg-surface sm:rounded-lg sm:border sm:border-muted">
             {/* ── Dialog header (input row) ─────────────────────────── */}

package/templates/base/pages/sitemap.xml.tsx

@@ -30,6 +30,14 @@ function escapeXml(str: string): string {
 }
 
 export default function Sitemap(): string {
+  // When sitemap is disabled, return an empty urlset so the route still
+  // resolves (returns XML, not 404) but contains no URLs.
+  if (!settings.sitemap) {
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+</urlset>`;
+  }
+
   const routeMap = enumerateAllRoutes();
   const siteUrlBase = (settings.siteUrl ?? "").replace(/\/$/, "");
 

package/templates/base/plugins/connect-adapter.mjs

@@ -123,19 +123,15 @@ export function connectToZfbHandler(middleware) {
          * @param {string | number | readonly string[]} value
          */
         setHeader(name, value) {
-          headers[name] = String(value);
+          // Store under lowercased key to avoid duplicate-case collisions
+          // when finish() merges headers — last-wins is then unambiguous.
+          headers[name.toLowerCase()] = String(value);
         },
         /** @param {string} name */
         getHeader(name) {
-          // Header lookup is case-insensitive in Node's real
-          // ServerResponse — mirror that so middlewares that probe an
-          // existing header before overwriting it (`if
-          // (!res.getHeader("Content-Type"))`) keep working.
-          const lower = name.toLowerCase();
-          for (const [k, v] of Object.entries(headers)) {
-            if (k.toLowerCase() === lower) return v;
-          }
-          return undefined;
+          // Keys are always stored lowercased (see setHeader), so a direct
+          // lowercased lookup is sufficient and avoids an O(n) scan.
+          return headers[name.toLowerCase()];
         },
         get headersSent() {
           return settled;

package/templates/base/plugins/search-index-plugin.mjs

@@ -28,8 +28,8 @@ export default {
   name: "search-index",
 
   /** @param {ZfbBuildHookContext} ctx */
-  postBuild(ctx) {
-    emitSearchIndex(/** @type {SearchIndexBuildOptions} */ (/** @type {unknown} */ ({
+  async postBuild(ctx) {
+    await emitSearchIndex(/** @type {SearchIndexBuildOptions} */ (/** @type {unknown} */ ({
       ...ctx.options,
       outDir: ctx.outDir,
       logger: ctx.logger,

package/templates/base/scripts/gen-z-index.mjs

@@ -0,0 +1,157 @@
+#!/usr/bin/env node
+// scripts/gen-z-index.mjs
+//
+// Codegen: rewrite the GENERATED:Z_INDEX marker block inside
+// src/styles/global.css from the single source of truth in
+// src/config/z-index-tokens.ts.
+//
+// The block is a Tailwind v4 `@theme { --z-index-<name>: <value>; }` for every
+// tier, so Tailwind generates `z-<name>` utilities (e.g. `--z-index-toolbar: 20`
+// → `.z-toolbar { z-index: 20 }`) and raw CSS can reference the same var via
+// `z-index: var(--z-index-<name>)`.
+//
+// Pure Node (fs only — NO npm deps). Idempotent: running twice produces no diff.
+//
+// Usage:
+//   node scripts/gen-z-index.mjs           # rewrite the block in global.css
+//   node scripts/gen-z-index.mjs --check   # verify committed block is up to date
+//                                          # (exit 1 on drift, no write)
+//
+// MAINTENANCE: edit src/config/z-index-tokens.ts (the source of truth), then run
+// `pnpm gen:z-index` and commit the regenerated global.css. Never hand-edit the
+// block between the BEGIN/END markers.
+
+import { readFileSync, writeFileSync } from "node:fs";
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ROOT = resolve(__dirname, "..");
+
+const TOKENS_PATH = resolve(ROOT, "src/config/z-index-tokens.ts");
+const CSS_PATH = resolve(ROOT, "src/styles/global.css");
+
+const BEGIN_MARKER = "GENERATED:Z_INDEX_BEGIN";
+const END_MARKER = "GENERATED:Z_INDEX_END";
+
+/**
+ * Parse the Z_INDEX_TIERS array out of z-index-tokens.ts WITHOUT importing it
+ * (this script is a dependency-free .mjs and cannot resolve TypeScript). Reads
+ * each `{ name: "...", value: <n>, ... }` object literal. Throws on a malformed
+ * source so drift between the parser and the file surfaces loudly.
+ */
+function parseTiers(src) {
+  const arrayMatch = src.match(
+    /export const Z_INDEX_TIERS[^=]*=\s*\[([\s\S]*?)\];/,
+  );
+  if (!arrayMatch) {
+    throw new Error(
+      `Could not locate "export const Z_INDEX_TIERS = [ ... ]" in ${TOKENS_PATH}`,
+    );
+  }
+  const body = arrayMatch[1];
+  const tiers = [];
+  // Each tier is a `{ ... }` object literal; iterate top-level braces.
+  const objectRe = /\{([\s\S]*?)\}/g;
+  let m;
+  while ((m = objectRe.exec(body)) !== null) {
+    const obj = m[1];
+    const nameMatch = obj.match(/name:\s*"([^"]+)"/);
+    const valueMatch = obj.match(/value:\s*(-?\d+)/);
+    if (!nameMatch || !valueMatch) {
+      throw new Error(
+        `Malformed tier object in Z_INDEX_TIERS (missing name/value): ${obj.trim()}`,
+      );
+    }
+    tiers.push({ name: nameMatch[1], value: Number(valueMatch[1]) });
+  }
+  if (tiers.length === 0) {
+    throw new Error(`Z_INDEX_TIERS in ${TOKENS_PATH} parsed to an empty list`);
+  }
+  return tiers;
+}
+
+/**
+ * Build the full generated block (markers included). Two leading spaces of
+ * indentation match the surrounding `@theme` style in global.css.
+ */
+function buildBlock(tiers) {
+  const lines = [];
+  lines.push(`  /* ${BEGIN_MARKER}`);
+  lines.push(
+    `   * GENERATED:Z_INDEX — do not hand-edit; run pnpm gen:z-index.`,
+  );
+  lines.push(
+    `   * Source of truth: src/config/z-index-tokens.ts. Tailwind v4 reads the`,
+  );
+  lines.push(
+    `   * --z-index-<name> theme key and generates a z-<name> utility. */`,
+  );
+  lines.push(`  @theme {`);
+  for (const tier of tiers) {
+    lines.push(`    --z-index-${tier.name}: ${tier.value};`);
+  }
+  lines.push(`  }`);
+  lines.push(`  /* ${END_MARKER} */`);
+  return lines.join("\n");
+}
+
+/**
+ * Replace the existing BEGIN…END block in `css` with `block`. Throws if the
+ * markers are missing (the block must be seeded once by hand — see global.css).
+ */
+function replaceBlock(css, block) {
+  const beginIdx = css.indexOf(BEGIN_MARKER);
+  const endIdx = css.indexOf(END_MARKER);
+  if (beginIdx === -1 || endIdx === -1) {
+    throw new Error(
+      `Could not find ${BEGIN_MARKER} … ${END_MARKER} markers in ${CSS_PATH}.\n` +
+        `Seed the marker block once by hand, then re-run the generator.`,
+    );
+  }
+  // Expand to the full comment line that opens the block ("  /* GENERATED:...")
+  // and to the end of the closing "*/ " line so the whole region is replaced.
+  const lineStart = css.lastIndexOf("\n", beginIdx) + 1;
+  const afterEnd = css.indexOf("\n", endIdx);
+  const lineEnd = afterEnd === -1 ? css.length : afterEnd;
+  return css.slice(0, lineStart) + block + css.slice(lineEnd);
+}
+
+function main() {
+  const check = process.argv.includes("--check");
+
+  const tokensSrc = readFileSync(TOKENS_PATH, "utf8");
+  const css = readFileSync(CSS_PATH, "utf8");
+
+  const tiers = parseTiers(tokensSrc);
+  const block = buildBlock(tiers);
+  const next = replaceBlock(css, block);
+
+  if (check) {
+    if (next !== css) {
+      console.error(
+        "z-index codegen drift detected: src/styles/global.css is out of date.",
+      );
+      console.error("Run `pnpm gen:z-index` and commit the result.");
+      return 1;
+    }
+    console.log(
+      `OK — z-index @theme block is up to date (${tiers.length} tiers).`,
+    );
+    return 0;
+  }
+
+  if (next === css) {
+    console.log(
+      `z-index @theme block already up to date (${tiers.length} tiers); no change.`,
+    );
+    return 0;
+  }
+  writeFileSync(CSS_PATH, next);
+  console.log(
+    `Wrote z-index @theme block to src/styles/global.css (${tiers.length} tiers).`,
+  );
+  return 0;
+}
+
+process.exit(main());

package/templates/base/src/components/sidebar-toggle.tsx

@@ -124,9 +124,14 @@ export default function SidebarToggle({
       {/* Backdrop overlay - mobile only.
           Rendered unconditionally; CSS `hidden` toggles visibility so
           the SSR DOM tree matches the hydrated tree (no subtree
-          mount/unmount across the hydration boundary). */}
+          mount/unmount across the hydration boundary).
+          `z-modal-backdrop` (50) intentionally sits ABOVE the header
+          (`z-toolbar`, 20): the open mobile drawer is a modal surface that
+          dims the whole viewport, header included. Closing is via tapping the
+          backdrop (onClick below), so the header hamburger being dimmed under
+          it is fine. */}
       <div
-        className={clsx("fixed inset-0 z-30 bg-overlay/30 lg:hidden", !open && "hidden")}
+        className={clsx("fixed inset-0 z-modal-backdrop bg-overlay/30 lg:hidden", !open && "hidden")}
         aria-hidden={!open}
         onClick={() => setOpen(false)}
       />
@@ -141,7 +146,7 @@ export default function SidebarToggle({
       <aside
         inert={!open}
         className={`
-          fixed top-[3.5rem] left-0 z-40 h-[calc(100vh-3.5rem)] w-[16rem] flex flex-col
+          fixed top-[3.5rem] left-0 z-modal h-[calc(100vh-3.5rem)] w-[16rem] flex flex-col
           border-r border-muted bg-bg transition-transform duration-200
           lg:hidden
           ${open ? "translate-x-0" : "-translate-x-full"}

package/templates/base/src/components/sidebar-tree.tsx

@@ -288,7 +288,7 @@ export default function SidebarTree({ nodes, currentSlug, rootMenuItems, backToM
             type="text"
             placeholder={filterPlaceholder}
             value={query}
-            onChange={(e) => setQuery(e.currentTarget.value)}
+            onInput={(e) => setQuery(e.currentTarget.value)}
             className="bg-transparent text-small outline-none w-full text-fg placeholder:text-muted"
           />
         </div>
@@ -419,7 +419,7 @@ function CategoryNode({
     <div className={`${depth === 0 ? "border-t border-muted" : ""} ${depth >= 1 && !isLast ? "relative" : ""}`}>
       {depth >= 1 && !isLast && isExpanded && (
         <div
-          className="absolute border-l border-solid border-muted z-10"
+          className="absolute border-l border-solid border-muted z-local-1"
           style={{
             left: connectorLeft(depth),
             top: 0,

package/templates/base/src/components/site-tree-nav.tsx

@@ -118,7 +118,7 @@ function CategoryNode({
     <div className={`${depth >= 1 && !isLast ? "relative" : ""}`}>
       {depth >= 1 && !isLast && open && (
         <div
-          className="absolute border-l border-dashed border-muted z-10"
+          className="absolute border-l border-dashed border-muted z-local-1"
           style={{
             left: connectorLeft(depth),
             top: 0,

package/templates/base/src/config/z-index-tokens.ts

@@ -0,0 +1,127 @@
+// z-index design tokens — single source of truth.
+//
+// This file is the ONE place z-index tiers are defined. The CSS `@theme` block
+// in `src/styles/global.css` is GENERATED from this list by
+// `scripts/gen-z-index.mjs` (run `pnpm gen:z-index`); never hand-edit the
+// generated block. `pnpm check:z-index` re-runs the generator into a buffer and
+// fails on drift, so the committed CSS can never silently diverge from this list.
+//
+// Strategy (from zudolab/zudo-css-wisdom z-index-strategy): semantic single-
+// namespace tokens — names describe ROLES, never magnitudes. One flat ordered
+// list. Values are deliberately gapped but otherwise arbitrary: renaming and
+// reordering is cheap, which is the whole point. Tailwind v4 reads the
+// `--z-index-<name>` theme key and generates a `z-<name>` utility, so e.g.
+// `@theme { --z-index-toolbar: 20 }` produces `.z-toolbar { z-index: 20 }`.
+//
+// `kind` distinguishes:
+//   - "global": a tier on the single global stacking scale (overlay chrome etc.)
+//   - "local":  anonymous reusable helpers for promoting a child WITHIN a parent
+//               stacking context (`isolation: isolate` / `position: relative`),
+//               not a position on the global scale.
+//
+// Rationale for the two zudo-doc-specific additions (NOT in the generic
+// overlay-centric strategy scale):
+//   - `sidebar` — persistent layout chrome (desktop sidebar, TOC, sidebar-toggle
+//     handle, resizer handle). The strategy's scale has no persistent-sidebar/TOC
+//     tier. `toolbar` (the sticky header) is deliberately placed ABOVE `sidebar`
+//     to preserve the existing header-wins ordering; they do not overlap
+//     spatially, but the historical relationship is kept explicit.
+//   - `drag` — transient drag affordance (sidebar-resizer ghost line). Replaces
+//     the old `z-9999` anti-pattern with a named top-of-steady-UI tier.
+//
+// `popover`, `toast`, and `tooltip` are reserved canonical tiers from the
+// strategy's scale — kept for completeness (and so downstream `create-zudo-doc`
+// users inherit the full scale) even though zudo-doc does not use them yet.
+
+export type ZIndexKind = "global" | "local";
+
+export interface ZIndexTier {
+  name: string;
+  value: number;
+  purpose: string;
+  kind: ZIndexKind;
+}
+
+export const Z_INDEX_TIERS: ZIndexTier[] = [
+  {
+    name: "content",
+    value: 0,
+    purpose: "default in-flow content (implicit baseline)",
+    kind: "global",
+  },
+  {
+    name: "local-1",
+    value: 1,
+    purpose: "child promotion inside an isolated parent stacking context",
+    kind: "local",
+  },
+  {
+    name: "local-2",
+    value: 2,
+    purpose: "child promotion inside an isolated parent stacking context",
+    kind: "local",
+  },
+  {
+    name: "local-3",
+    value: 3,
+    purpose: "child promotion inside an isolated parent stacking context",
+    kind: "local",
+  },
+  {
+    name: "sidebar",
+    value: 10,
+    purpose:
+      "persistent layout chrome: desktop sidebar, TOC, sidebar-toggle handle, resizer handle",
+    kind: "global",
+  },
+  {
+    name: "toolbar",
+    value: 20,
+    purpose: "sticky top header (sits above sidebar chrome)",
+    kind: "global",
+  },
+  {
+    name: "dropdown",
+    value: 30,
+    purpose: "header menus, version/language switchers",
+    kind: "global",
+  },
+  {
+    name: "popover",
+    value: 40,
+    purpose: "reserved — inline popovers (canonical scale; not yet used)",
+    kind: "global",
+  },
+  {
+    name: "modal-backdrop",
+    value: 50,
+    purpose: "mobile drawer backdrop, <dialog> ::backdrop",
+    kind: "global",
+  },
+  {
+    name: "modal",
+    value: 60,
+    purpose: "mobile sidebar drawer panel, search <dialog>",
+    kind: "global",
+  },
+  {
+    name: "toast",
+    value: 70,
+    purpose: "reserved — transient notifications (canonical scale; not yet used)",
+    kind: "global",
+  },
+  {
+    name: "tooltip",
+    value: 80,
+    purpose:
+      "reserved — highest steady UI layer, below only the transient drag tier (canonical scale; not yet used)",
+    kind: "global",
+  },
+  {
+    name: "drag",
+    value: 90,
+    purpose:
+      "transient drag affordance: sidebar-resizer ghost line (replaces the z-9999 anti-pattern)",
+    kind: "global",
+  },
+];

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

@@ -216,6 +216,37 @@
   --breakpoint-xl: 1280px;
 }
 
+/* ========================================
+ * Z-index tiers — semantic, single-namespace scale.
+ *
+ * The @theme block below is GENERATED from src/config/z-index-tokens.ts
+ * (the single source of truth) by `pnpm gen:z-index`. Tailwind v4 reads the
+ * --z-index-<name> theme key and generates a `z-<name>` utility, so e.g.
+ * --z-index-toolbar: 20 produces `.z-toolbar { z-index: 20 }`; raw CSS can
+ * also reference `z-index: var(--z-index-<name>)`. `pnpm check:z-index` fails
+ * on drift. Do NOT hand-edit between the BEGIN/END markers.
+ * ======================================== */
+  /* GENERATED:Z_INDEX_BEGIN
+   * GENERATED:Z_INDEX — do not hand-edit; run pnpm gen:z-index.
+   * Source of truth: src/config/z-index-tokens.ts. Tailwind v4 reads the
+   * --z-index-<name> theme key and generates a z-<name> utility. */
+  @theme {
+    --z-index-content: 0;
+    --z-index-local-1: 1;
+    --z-index-local-2: 2;
+    --z-index-local-3: 3;
+    --z-index-sidebar: 10;
+    --z-index-toolbar: 20;
+    --z-index-dropdown: 30;
+    --z-index-popover: 40;
+    --z-index-modal-backdrop: 50;
+    --z-index-modal: 60;
+    --z-index-toast: 70;
+    --z-index-tooltip: 80;
+    --z-index-drag: 90;
+  }
+  /* GENERATED:Z_INDEX_END */
+
 :root {
   /* Default responsive range; sidebar-resizer.ts allows 192–448px for explicit resizing */
   --zd-sidebar-w: clamp(14rem, 20vw, 22rem);
@@ -696,7 +727,7 @@ pre[class^="syntect-"].word-wrap code {
   gap: var(--spacing-hsp-2xs);
   opacity: 0;
   transition: opacity 0.15s;
-  z-index: 1;
+  z-index: var(--z-index-local-1);
 }
 
 .code-block-wrapper:hover .code-buttons,
@@ -1152,7 +1183,7 @@ pre[class^="syntect-"] .line .highlighted-word {
   border: none;
   background: transparent;
   cursor: pointer;
-  z-index: 1;
+  z-index: var(--z-index-local-1);
   transition: opacity var(--default-transition-duration);
 }
 
@@ -1161,12 +1192,12 @@ pre[class^="syntect-"] .line .highlighted-word {
   position: absolute;
   inset: 0;
   background: color-mix(in oklch, var(--color-image-overlay-bg) 80%, transparent);
-  z-index: 0;
+  z-index: var(--z-index-local-1);
 }
 
 .zd-enlarge-btn > svg {
   position: relative;
-  z-index: 1;
+  z-index: var(--z-index-local-2);
   width: var(--spacing-icon-sm);
   height: var(--spacing-icon-sm);
   color: var(--color-image-overlay-fg);
@@ -1201,7 +1232,7 @@ dialog.zd-enlarge-dialog::backdrop {
   border: none;
   background: transparent;
   cursor: pointer;
-  z-index: 1;
+  z-index: var(--z-index-local-1);
   transition: opacity var(--default-transition-duration);
 }
 
@@ -1214,12 +1245,12 @@ dialog.zd-enlarge-dialog::backdrop {
   position: absolute;
   inset: 0;
   background: color-mix(in oklch, var(--color-image-overlay-bg) 80%, transparent);
-  z-index: 0;
+  z-index: var(--z-index-local-1);
 }
 
 .zd-enlarge-dialog-close > svg {
   position: relative;
-  z-index: 1;
+  z-index: var(--z-index-local-2);
   width: var(--spacing-icon-lg);
   height: var(--spacing-icon-lg);
   color: var(--color-image-overlay-fg);

package/templates/features/docHistory/files/plugins/doc-history-plugin.mjs

@@ -35,6 +35,22 @@ export default {
   /** @param {ZfbBuildHookContext} ctx */
   async preBuild(ctx) {
     const { docsDir, locales } = ctx.options;
+    // Validate each locale entry before passing downstream so a misconfigured
+    // locales map surfaces a clear error instead of a confusing runtime crash.
+    if (locales != null) {
+      for (const [key, entry] of Object.entries(/** @type {Record<string, unknown>} */ (locales))) {
+        if (
+          entry == null ||
+          typeof entry !== "object" ||
+          typeof /** @type {any} */ (entry).dir !== "string" ||
+          /** @type {any} */ (entry).dir.length === 0
+        ) {
+          throw new Error(
+            `[doc-history] invalid locales entry "${key}": expected { dir: string }`,
+          );
+        }
+      }
+    }
     await runDocHistoryMetaStep({
       projectRoot: ctx.projectRoot,
       docsDir: typeof docsDir === "string" ? docsDir : "src/content/docs",
@@ -47,10 +63,22 @@ export default {
 
   /** @param {ZfbBuildHookContext} ctx */
   async postBuild(ctx) {
-    await runDocHistoryPostBuild(
-      /** @type {import("@takazudo/zudo-doc/integrations/doc-history").DocHistoryOptions} */ (/** @type {unknown} */ (ctx.options)),
-      { outDir: ctx.outDir, logger: ctx.logger },
-    );
+    try {
+      await runDocHistoryPostBuild(
+        /** @type {import("@takazudo/zudo-doc/integrations/doc-history").DocHistoryOptions} */ (/** @type {unknown} */ (ctx.options)),
+        { outDir: ctx.outDir, logger: ctx.logger },
+      );
+    } catch (err) {
+      // postBuild dropdown JSON is redundant: the parallel build-history CI job
+      // is the deployed source of truth. Downgrade failures to a warning so a
+      // transient git/CLI error does not red the build-site job.
+      const msg = err instanceof Error ? err.message : String(err);
+      if (ctx.logger?.warn) {
+        ctx.logger.warn(`[doc-history] postBuild failed (non-fatal): ${msg}`);
+      } else {
+        console.warn(`[doc-history] postBuild failed (non-fatal): ${msg}`);
+      }
+    }
   },
 
   /** @param {ZfbDevMiddlewareContext} ctx */

package/templates/features/docHistory/files/src/components/doc-history.tsx

@@ -559,10 +559,17 @@ export function DocHistory({ slug, locale, basePath = "/" }: DocHistoryProps) {
       )}
 
       {/* Full-screen dialog — renders in top layer, above all stacking contexts */}
+      {/* z-modal / backdrop:z-modal-backdrop are defense-in-depth for the
+          SPA-swap window: clicking a history entry link swaps the page body
+          while this dialog is still open, and a native showModal() dialog can
+          momentarily lose top-layer promotion and fall back to z-index:auto,
+          flashing behind the header/sidebar. The explicit modal-tier z-index
+          keeps it above all chrome during that window. Intentionally redundant
+          in the normal (top-layer) case — do not remove as "redundant". */}
       <dialog
         ref={dialogRef}
         aria-label="Document revision history"
-        className="doc-history-panel fixed inset-0 m-0 h-full w-full max-h-full max-w-full bg-bg border-none p-0 backdrop:bg-bg/30"
+        className="doc-history-panel z-modal fixed inset-0 m-0 h-full w-full max-h-full max-w-full bg-bg border-none p-0 backdrop:z-modal-backdrop backdrop:bg-bg/30"
         style={{ color: "var(--color-fg)" }}
       >
         {/* Panel header */}

package/templates/features/i18n/files/pages/[locale]/index.tsx

@@ -67,6 +67,15 @@ interface PageArgs {
 export default function LocaleIndexPage({ params }: PageArgs): JSX.Element {
   const locale = params.locale;
 
+  // Guard: paths() only emits routes for locales defined in settings.locales,
+  // but the component can still be exercised with an unconfigured locale value
+  // (e.g. during testing or if the router dispatches an unexpected param).
+  // Fail loudly rather than silently serving EN content under a bogus prefix.
+  const cfg = getLocaleConfig(locale);
+  if (!cfg) {
+    throw new Error(`LocaleIndexPage: locale "${locale}" is not configured in settings.locales`);
+  }
+
   // Identity-stable, locale-first merge with EN fallback (shared `navDocs`
   // instance). categoryMeta is intentionally locale-dir-only here — this page
   // historically did NOT merge in base meta (unlike the locale doc route), so
@@ -75,10 +84,7 @@ export default function LocaleIndexPage({ params }: PageArgs): JSX.Element {
     applyDefaultLocaleOnlyFilter: true,
     keepUnlisted: true,
   });
-  const localeConfig = getLocaleConfig(locale);
-  const categoryMeta = localeConfig
-    ? loadCategoryMeta(localeConfig.dir)
-    : loadCategoryMeta(settings.docsDir);
+  const categoryMeta = loadCategoryMeta(cfg.dir);
 
   const tree = buildNavTree(navDocs, locale as Locale, categoryMeta);
   const categoryOrder = getCategoryOrder();

package/templates/features/imageEnlarge/files/src/components/image-enlarge.tsx

@@ -18,8 +18,17 @@ interface ImageData {
 // agree on class string and inline style — otherwise the dist HTML and the
 // post-hydration DOM disagree on size / position and the first interaction
 // flashes. Sourcing both from the same constants closes the drift gap.
+//
+// z-modal / backdrop:z-modal-backdrop are defense-in-depth for the SPA-swap
+// window: if this dialog is still open while the page body is swapped, a native
+// showModal() dialog can lose top-layer promotion and fall back to z-index:auto,
+// flashing behind the header/sidebar. `backdrop:z-modal-backdrop` targets the
+// native `::backdrop` (present for every showModal() dialog even with no backdrop
+// tint). The explicit modal-tier z-index keeps it above all chrome during that
+// window. Intentionally redundant in the normal (top-layer) case — do not remove
+// as "redundant".
 const DIALOG_CLASS =
-  "zd-enlarge-dialog mx-auto max-h-[90vh] max-w-[90vw] overflow-hidden border border-muted bg-surface p-0";
+  "zd-enlarge-dialog z-modal mx-auto max-h-[90vh] max-w-[90vw] overflow-hidden border border-muted bg-surface p-0 backdrop:z-modal-backdrop";
 // Center the modal with `inset: 0; margin: auto` rather than a transform.
 // A `transform` on the dialog would establish a containing block for its
 // `position: fixed` descendants, which would trap the `.zd-enlarge-dialog-close`

package/templates/features/llmsTxt/files/plugins/llms-txt-plugin.mjs

@@ -32,8 +32,8 @@ export default {
   name: "llms-txt",
 
   /** @param {ZfbBuildHookContext} ctx */
-  postBuild(ctx) {
-    emitLlmsTxt(/** @type {LlmsTxtEmitOptions} */ (/** @type {unknown} */ ({
+  async postBuild(ctx) {
+    await emitLlmsTxt(/** @type {LlmsTxtEmitOptions} */ (/** @type {unknown} */ ({
       ...ctx.options,
       outDir: ctx.outDir,
       // siteUrl is normalised to undefined when falsy because the runner
@@ -70,6 +70,13 @@ export default {
         if (locale && typeof locale === "object" && typeof locale.code === "string") {
           ctx.register(`${basePrefix}/${locale.code}/llms.txt`, handler);
           ctx.register(`${basePrefix}/${locale.code}/llms-full.txt`, handler);
+        } else {
+          const repr = JSON.stringify(locale);
+          if (ctx.logger?.warn) {
+            ctx.logger.warn(`[llms-txt] skipping malformed locale entry (expected { code: string }): ${repr}`);
+          } else {
+            console.warn(`[llms-txt] skipping malformed locale entry (expected { code: string }): ${repr}`);
+          }
         }
       }
     }

package/templates/features/sidebarToggle/files/src/components/desktop-sidebar-toggle.tsx

@@ -101,7 +101,7 @@ export default function DesktopSidebarToggle() {
     <button
       type="button"
       onClick={() => setVisible((v) => !v)}
-      className="zd-desktop-sidebar-toggle hidden lg:flex fixed bottom-vsp-xl z-40 items-center justify-center w-[1.5rem] h-[3rem] bg-surface border border-muted border-l-0 rounded-r-DEFAULT text-muted cursor-pointer transition-[left,color] duration-200 ease-in-out hover:text-fg"
+      className="zd-desktop-sidebar-toggle hidden lg:flex fixed bottom-vsp-xl z-sidebar items-center justify-center w-[1.5rem] h-[3rem] bg-surface border border-muted border-l-0 rounded-r-DEFAULT text-muted cursor-pointer transition-[left,color] duration-200 ease-in-out hover:text-fg"
       aria-label={visible ? 'Hide sidebar' : 'Show sidebar'}
       aria-pressed={visible}
       data-zfb-transition-persist="desktop-sidebar-toggle"

package/templates/features/tauri/files/src/components/find-bar.tsx

@@ -70,7 +70,7 @@ export function FindBar({ visible, onClose, findInPage, containerSelector }: Fin
   if (!visible) return null;
 
   return (
-    <div className="fixed top-[3.5rem] right-0 z-50 flex items-center gap-hsp-sm py-hsp-xs px-hsp-md bg-surface border-b border-l border-muted rounded-bl-lg shadow-md">
+    <div className="fixed top-[3.5rem] right-0 z-dropdown flex items-center gap-hsp-sm py-hsp-xs px-hsp-md bg-surface border-b border-l border-muted rounded-bl-lg shadow-md">
       <input
         ref={inputRef}
         className="w-48 py-[4px] px-hsp-sm rounded text-small bg-bg border border-muted text-fg outline-none focus:border-accent"

package/templates/features/tauriDev/files/src-tauri-dev/capabilities/default.json

@@ -2,6 +2,6 @@
   "identifier": "default",
   "description": "Default capabilities for the main window",
   "windows": ["main"],
-  "remote": { "urls": ["http://localhost:*/*"] },
+  "remote": { "urls": ["http://localhost:*/**"] },
   "permissions": ["core:default"]
 }