create-zudo-doc 0.2.1 → 0.2.3

package/dist/compose.d.ts

@@ -78,9 +78,8 @@ export declare function validateDependencies(features: FeatureDefinition[], allS
  * - `pages/_mdx-components.ts` — image-enlarge.ts injects the
  *   EnlargeableParagraph p-override (ENLARGE_SVG, EnlargeableParagraph def,
  *   `p:` map entry) when imageEnlarge is enabled.
- *
- * The .tsx anchor form is still supported in `ANCHOR_LINE_RE` for forward
- * compatibility.
+ * - `pages/lib/_body-end-islands.tsx` — tauri.ts injects the FindInPageInit
+ *   island (import, displayName, Island mount) when tauri is enabled.
  */
 export declare const ANCHOR_FILES: string[];
 /**

package/dist/compose.js

@@ -164,11 +164,14 @@ export function validateDependencies(features, allSelectedNames) {
  * - `pages/_mdx-components.ts` — image-enlarge.ts injects the
  *   EnlargeableParagraph p-override (ENLARGE_SVG, EnlargeableParagraph def,
  *   `p:` map entry) when imageEnlarge is enabled.
- *
- * The .tsx anchor form is still supported in `ANCHOR_LINE_RE` for forward
- * compatibility.
+ * - `pages/lib/_body-end-islands.tsx` — tauri.ts injects the FindInPageInit
+ *   island (import, displayName, Island mount) when tauri is enabled.
  */
-export const ANCHOR_FILES = ["src/styles/global.css", "pages/_mdx-components.ts"];
+export const ANCHOR_FILES = [
+    "src/styles/global.css",
+    "pages/_mdx-components.ts",
+    "pages/lib/_body-end-islands.tsx",
+];
 /**
  * Main composition entry point. Orchestrates the full feature composition
  * pipeline for a generated project.

package/dist/features/tauri.d.ts

@@ -2,10 +2,15 @@ import type { FeatureModule } from "../compose.js";
 /**
  * Tauri feature.
  *
- * W7A (#1736): post-cutover, the FindInPage island is mounted by the
- * pages/lib body-end wrapper. The find-match highlight CSS is unconditional
- * in `templates/base/src/styles/global.css` (matches host). Only the
- * postProcess hooks (Cargo.toml / tauri.conf.json / .gitignore patches)
- * remain feature-scoped.
+ * #2052: the FindInPageInit island (Cmd/Ctrl+F find bar for the Tauri
+ * WebView, where the browser-native find UI is unavailable) is wired into
+ * `pages/lib/_body-end-islands.tsx` via the three injections below — import,
+ * displayName, and Island mount. zfb's island scanner only registers
+ * components reachable through static import chains (page → wrapper →
+ * component), so without this injection the feature-copied component files
+ * are orphaned dead code that never hydrates. The find-match highlight CSS
+ * is unconditional in `templates/base/src/styles/global.css` (matches host);
+ * the component runtime-gates itself (renders null unless
+ * `window.__TAURI_INTERNALS__` exists), so no settings field is needed.
  */
 export declare const tauriFeature: FeatureModule;

package/dist/features/tauri.js

@@ -3,15 +3,58 @@ import path from "path";
 /**
  * Tauri feature.
  *
- * W7A (#1736): post-cutover, the FindInPage island is mounted by the
- * pages/lib body-end wrapper. The find-match highlight CSS is unconditional
- * in `templates/base/src/styles/global.css` (matches host). Only the
- * postProcess hooks (Cargo.toml / tauri.conf.json / .gitignore patches)
- * remain feature-scoped.
+ * #2052: the FindInPageInit island (Cmd/Ctrl+F find bar for the Tauri
+ * WebView, where the browser-native find UI is unavailable) is wired into
+ * `pages/lib/_body-end-islands.tsx` via the three injections below — import,
+ * displayName, and Island mount. zfb's island scanner only registers
+ * components reachable through static import chains (page → wrapper →
+ * component), so without this injection the feature-copied component files
+ * are orphaned dead code that never hydrates. The find-match highlight CSS
+ * is unconditional in `templates/base/src/styles/global.css` (matches host);
+ * the component runtime-gates itself (renders null unless
+ * `window.__TAURI_INTERNALS__` exists), so no settings field is needed.
  */
 export const tauriFeature = (choices) => ({
     name: "tauri",
-    injections: [],
+    injections: [
+        // 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 FindInPageInit from "@/components/find-in-page-init";`,
+        },
+        // 2. Stable island marker name (same belt-and-braces guard as 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: `(FindInPageInit as { displayName?: string }).displayName = "FindInPageInit";`,
+        },
+        // 3. Island mount. Inserted AFTER the
+        //    `{/* @slot:body-end-islands:extra-islands */}` anchor.
+        //    when="load" (not "idle"): the island's job is to intercept
+        //    Cmd/Ctrl+F via a keydown listener, so it must hydrate as soon as
+        //    the islands runtime mounts — same rationale as the
+        //    clientRouterBootstrap click intercept above it. Deferring to idle
+        //    would leave a post-load window where Cmd+F does nothing, which is
+        //    the very bug this injection fixes.
+        {
+            file: "pages/lib/_body-end-islands.tsx",
+            anchor: "{/* @slot:body-end-islands:extra-islands */}",
+            position: "after",
+            content: `      {/* Tauri-only find-in-page (Cmd/Ctrl+F) bar. Renders null outside
+          a Tauri WebView, so the island is inert in plain browser builds
+          of the same scaffold. */}
+      {Island({
+        when: "load",
+        children: <FindInPageInit />,
+      }) as unknown as VNode}`,
+        },
+    ],
     postProcess: async (targetDir) => {
         // Patch Cargo.toml package name
         const cargoPath = path.join(targetDir, "src-tauri/Cargo.toml");

package/dist/scaffold.js

@@ -269,16 +269,24 @@ function generatePackageJson(choices) {
         // cross-file anchor validation. BREAKING upstream: the no-op
         // `linkValidation.allowExternal` knob was removed — neither the host nor
         // the generated config ever emitted it, so no migration is needed here.
-        "@takazudo/zfb": "0.1.0-next.38",
-        "@takazudo/zfb-runtime": "0.1.0-next.38",
+        // next.39 is features + fixes, no breaking changes:
+        // npm-dist `"use client"` island scanning, link-resolution fixes for
+        // directory-style hrefs, and island-registry hardening (warns on island
+        // marker-name collisions).
+        // next.40 (current pin) flips `zfb dev` to lazy rendering by default —
+        // 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.
+        "@takazudo/zfb": "0.1.0-next.40",
+        "@takazudo/zfb-runtime": "0.1.0-next.40",
         // zfb-adapter-cloudflare — required for any route with `prerender = false`.
         // Pinned in lockstep with @takazudo/zfb.
-        "@takazudo/zfb-adapter-cloudflare": "0.1.0-next.38",
+        "@takazudo/zfb-adapter-cloudflare": "0.1.0-next.40",
         // @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.1",
+        "@takazudo/zudo-doc": "^0.2.3",
         // 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
@@ -332,7 +340,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.1";
+        deps["@takazudo/zudo-doc-history-server"] = "^0.2.3";
         // 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

@@ -69,7 +69,10 @@ export function generateSettingsFile(choices) {
         lines.push(`  } satisfies Record<string, LocaleConfig>,`);
     }
     else {
-        lines.push(`  locales: {} satisfies Record<string, LocaleConfig>,`);
+        // `as`, not `satisfies`: satisfies keeps the inferred type at literal {},
+        // so Object.entries(settings.locales) in the generated zfb.config.ts
+        // yields unknown values and `zfb check` fails with TS18046 (#2053).
+        lines.push(`  locales: {} as Record<string, LocaleConfig>,`);
     }
     // mermaid is controlled by the markdown.features block in zfb.config.ts
     // (zfb next.12+). This field is retained for compatibility with framework

package/package.json

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

package/templates/base/pages/404.tsx

@@ -36,6 +36,11 @@ export default function NotFoundPage(): JSX.Element {
       noindex={true}
       hideSidebar={true}
       hideToc={true}
+      // Empty fragment suppresses DocLayoutWithDefaults' empty-data default
+      // Sidebar island — its marker never hydrates for published-package
+      // consumers (zfb#999) and zfb >= next.38 warns about it; the sidebar is
+      // hidden on this page anyway (zudolab/zudo-doc#2057).
+      sidebarOverride={<></>}
       headerOverride={<HeaderWithDefaults lang={locale} />}
       footerOverride={<FooterWithDefaults lang={locale} />}
       bodyEndComponents={<BodyEndIslands basePath={settings.base ?? "/"} />}

package/templates/base/pages/index.tsx

@@ -65,6 +65,11 @@ export default function IndexPage(): JSX.Element {
       noindex={settings.noindex}
       hideSidebar={true}
       hideToc={true}
+      // Empty fragment suppresses DocLayoutWithDefaults' empty-data default
+      // Sidebar island — its marker never hydrates for published-package
+      // consumers (zfb#999) and zfb >= next.38 warns about it; the sidebar is
+      // hidden on this page anyway (zudolab/zudo-doc#2057).
+      sidebarOverride={<></>}
       headerOverride={<HeaderWithDefaults lang={locale} currentPath={withBase("/")} />}
       footerOverride={<FooterWithDefaults lang={locale} />}
       bodyEndComponents={<BodyEndIslands basePath={settings.base ?? "/"} />}

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

@@ -37,6 +37,7 @@ import ClientRouterBootstrap from "@/components/client-router-bootstrap";
 import DesignTokenPanelBootstrap from "@/components/design-token-panel-bootstrap";
 import ImageEnlarge, { ImageEnlargeSsrFallback } from "@/components/image-enlarge";
 import { PageLoadingOverlay } from "@takazudo/zudo-doc/page-loading";
+// @slot:body-end-islands:imports
 
 // Set explicit `displayName` on each default-exported island so zfb's
 // `captureComponentName` produces a stable marker even after the SSR
@@ -51,6 +52,7 @@ import { PageLoadingOverlay } from "@takazudo/zudo-doc/page-loading";
 (DesignTokenPanelBootstrap as { displayName?: string }).displayName =
   "DesignTokenPanelBootstrap";
 (ImageEnlarge as { displayName?: string }).displayName = "ImageEnlarge";
+// @slot:body-end-islands:display-names
 
 /**
  * Default sr-only label rendered as the AiChatModal SSR fallback. This
@@ -107,10 +109,14 @@ export interface BodyEndIslandsProps {
 }
 
 /**
- * The three default body-end islands every doc page mounts: 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).
+ * 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
+ * island marker nor a misleading landmark (zudolab/zudo-doc#2058).
  *
  * Each island is wrapped in `<Island ssrFallback>` so the heavy
  * component is NOT evaluated server-side — they depend on
@@ -118,9 +124,10 @@ export interface BodyEndIslandsProps {
  * fetch, etc. The hydration runtime swaps each placeholder on the
  * client.
  *
- * The `<h2 class="sr-only">AI Assistant</h2>` heading is emitted in
- * the SSG output so screen readers and crawlers can discover the chat
- * section landmark before JS hydration.
+ * When `settings.aiAssistant` is enabled, the
+ * `<h2 class="sr-only">AI Assistant</h2>` heading is emitted in the SSG
+ * output so screen readers and crawlers can discover the chat section
+ * landmark before JS hydration.
  */
 export function BodyEndIslands({
   basePath,
@@ -161,26 +168,52 @@ export function BodyEndIslands({
         )
       : null;
 
-  // Use a visually-hidden paragraph as the AiChatModal SSR fallback so
-  // the body label is present in static HTML for screen readers before
-  // JS hydration. sr-only keeps it invisible to sighted users.
-  const aiChat = Island({
-    ssrFallback: <p class="sr-only">{aiChatBodyLabel}</p>,
-    children: <AiChatModal basePath={basePath} />,
-  }) as unknown as VNode;
+  // 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.
+  //
+  // KNOWN CAVEAT: zfb's island scanner walks the static `"use client"`
+  // import chain, so gating this JSX removes the SSR marker and heading but
+  // may NOT strip the AiChatModal bundle from the build output. Marker
+  // removal is the agreed first fix (#2058); bundle stripping is out of scope.
+  //
+  // The sr-only <p> fallback keeps the body label in static HTML for screen
+  // readers before JS hydration; sr-only keeps it invisible to sighted users.
+  const aiAssistant = settings.aiAssistant ? (
+    <>
+      {/* Emits the "AI Assistant" heading in the SSG output so screen
+          readers can discover the chat section landmark before JS
+          hydration. */}
+      <h2 class="sr-only">AI Assistant</h2>
+      {
+        Island({
+          ssrFallback: <p class="sr-only">{aiChatBodyLabel}</p>,
+          children: <AiChatModal basePath={basePath} />,
+        }) as unknown as VNode
+      }
+    </>
+  ) : null;
 
-  // Wave 11 (zudolab/zudo-doc#1355): the SSR fallback is the empty,
-  // closed `<dialog class="zd-enlarge-dialog ...">` shell so the dist
-  // HTML carries one dialog from the start. Without this the smoke
-  // "exactly one zd-enlarge-dialog element" assertion sees zero
-  // (skip-ssr placeholders are empty divs) and the no-JS path has no
-  // dialog at all. Hydration replaces this shell with the real
-  // ImageEnlarge component when the page goes idle.
-  const imageEnlarge = Island({
-    when: "idle",
-    ssrFallback: <ImageEnlargeSsrFallback />,
-    children: <ImageEnlarge />,
-  }) as unknown as VNode;
+  // Gated on `settings.imageEnlarge` (zudolab/zudo-doc#2058). Same caveat as
+  // the AI assistant gating: removing this JSX drops the SSR dialog shell and
+  // island marker, but the bundle may persist via the static import scan.
+  //
+  // Wave 11 (zudolab/zudo-doc#1355): the SSR fallback is the empty, closed
+  // `<dialog class="zd-enlarge-dialog ...">` shell so the dist HTML carries
+  // one dialog from the start. Without this the smoke "exactly one
+  // zd-enlarge-dialog element" assertion sees zero (skip-ssr placeholders are
+  // empty divs) and the no-JS path has no dialog at all. Hydration replaces
+  // this shell with the real ImageEnlarge component when the page goes idle.
+  const imageEnlarge = settings.imageEnlarge
+    ? (Island({
+        when: "idle",
+        ssrFallback: <ImageEnlargeSsrFallback />,
+        children: <ImageEnlarge />,
+      }) as unknown as VNode)
+    : null;
 
   return (
     <>
@@ -190,12 +223,9 @@ export function BodyEndIslands({
       <PageLoadingOverlay />
       {clientRouterBootstrap}
       {designTokenPanelBootstrap}
-      {/* Emits the "AI Assistant" heading in the SSG output so screen
-          readers can discover the chat section landmark before JS
-          hydration. */}
-      <h2 class="sr-only">AI Assistant</h2>
-      {aiChat}
+      {aiAssistant}
       {imageEnlarge}
+      {/* @slot:body-end-islands:extra-islands */}
     </>
   );
 }

package/templates/base/pages/lib/_doc-page-shell.tsx

@@ -17,9 +17,12 @@
 // keeping the create-zudo-doc template copies byte-identical to the host.
 
 import type { ComponentChildren, JSX, VNode } from "preact";
+import { Island } from "@takazudo/zfb";
 import { settings } from "@/config/settings";
 import type { NavNode } from "@/utils/docs";
 import { DocLayoutWithDefaults } from "@takazudo/zudo-doc/doclayout";
+import { Toc, MobileToc } from "@takazudo/zudo-doc/toc";
+import { getTocTitle } from "./_toc-title";
 import { Breadcrumb } from "@takazudo/zudo-doc/breadcrumb";
 import { NavCardGrid } from "@takazudo/zudo-doc/nav-indexing";
 import { HeadWithDefaults } from "./_head-with-defaults";
@@ -145,6 +148,31 @@ export function DocPageShell(props: DocPageShellProps): JSX.Element {
     docHistorySlot,
   } = props;
 
+  // TOC overrides: mount the package Toc/MobileToc with the host-resolved
+  // locale-aware `tocTitle`. The gating mirrors the package's
+  // `shouldRenderDefaultToc` exactly (`!hideToc && headings.length > 0`) so an
+  // undefined override never silently falls back to the package default with a
+  // different title. Each is wrapped in `<Island when="load">` here (the call
+  // site), matching how the package wraps its own default. Hydrating these
+  // npm-dist "use client" components requires zfb >= 0.1.0-next.39, whose
+  // scanner registers node_modules islands (zfb#999/#1001) — the former
+  // scanner-visible local shims (#2057) are gone; re-adding them would
+  // recreate island marker-name collisions.
+  const tocTitle = getTocTitle(locale);
+  const shouldRenderToc = !hideToc && headings.length > 0;
+  const tocOverride = shouldRenderToc
+    ? (Island({
+        when: "load",
+        children: <Toc headings={headings} title={tocTitle} />,
+      }) as unknown as VNode)
+    : undefined;
+  const mobileTocOverride = shouldRenderToc
+    ? (Island({
+        when: "load",
+        children: <MobileToc headings={headings} title={tocTitle} />,
+      }) as unknown as VNode)
+    : undefined;
+
   return (
     <DocLayoutWithDefaults
       title={composeMetaTitle(title)}
@@ -183,6 +211,8 @@ export function DocPageShell(props: DocPageShellProps): JSX.Element {
           currentPath={currentPath}
         />
       }
+      tocOverride={tocOverride}
+      mobileTocOverride={mobileTocOverride}
       afterSidebar={<SidebarPrepaint />}
       footerOverride={<FooterWithDefaults lang={locale} />}
       bodyEndComponents={<DocBodyEnd />}

package/templates/base/pages/lib/_header-with-defaults.tsx

@@ -45,10 +45,11 @@ import {
   VersionSwitcher,
   type VersionSwitcherLabels,
 } from "@takazudo/zudo-doc/i18n-version";
-// BARE (non-island-wrapped) ThemeToggle from the dedicated subpath
-// (#2012 E2). The `./theme` barrel exports an Island-wrapped variant;
-// this wrapper composes its own Island below, and the bare subpath
-// avoids nesting an island inside an island.
+// The bare (non-island-wrapped) package ThemeToggle, imported straight from
+// the npm subpath: zfb >= 0.1.0-next.39 scans "use client" modules under
+// node_modules (zfb#999/#1001), so the marker registers without the former
+// project-source shim (#2048/#2057). This header composes its own Island
+// below, avoiding nesting an island inside an island.
 import { ThemeToggle } from "@takazudo/zudo-doc/theme-toggle";
 import SidebarToggle from "@/components/sidebar-toggle";
 import { settings } from "@/config/settings";

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

@@ -249,6 +249,9 @@ export const SEARCH_WIDGET_SCRIPT = /* javascript */ `(function () {
           self._entries = Array.isArray(data) ? data : (data.entries || []);
           prepareLc(self._entries);
           self._loading = false;
+          // Clear the unavailable flag BEFORE re-running search so a successful
+          // retry (e.g. via the openDialog() reload path) fully recovers (#2062).
+          self._indexUnavailable = false;
           // If user already typed, search now
           if (self._input && self._input.value.trim()) {
             self.search();
@@ -277,6 +280,20 @@ export const SEARCH_WIDGET_SCRIPT = /* javascript */ `(function () {
       }
 
       if (!this._entries) {
+        // Index failed to load: show the terminal "Search unavailable" state and
+        // stop — do NOT show "Loading search index…" or refetch on every
+        // keystroke (#2062). The openDialog() reload path is the intended retry
+        // trigger. Clear any stale result state/count/sentinel first.
+        if (this._indexUnavailable) {
+          this.teardownSentinel();
+          this._allResults = [];
+          this._shownCount = 0;
+          if (this._results) {
+            this._results.innerHTML = "<p class=\\"text-small text-muted\\">Search unavailable</p>";
+          }
+          this.updateCount();
+          return;
+        }
         if (this._results) {
           this._results.innerHTML = "<p class=\\"text-small text-muted\\">Loading search index\\u2026</p>";
         }

package/templates/base/pages/lib/_toc-title.ts

@@ -0,0 +1,22 @@
+// TOC section-label resolver for the Toc/MobileToc overrides mounted by
+// `_doc-page-shell.tsx`. Hand-mirrors `getTocTitle`, which the zudo-doc
+// package exports from "@takazudo/zudo-doc/toc" in versions > 0.2.2. The
+// published version this scaffold installs (<= 0.2.2) does not yet export it,
+// so the tiny lang→title map is duplicated here. After bumping the
+// @takazudo/zudo-doc dependency past 0.2.2 you can replace this whole file
+// with: export { getTocTitle } from "@takazudo/zudo-doc/toc";
+const TOC_TITLES: Record<string, string> = {
+  en: "On this page",
+  ja: "目次",
+  de: "Auf dieser Seite",
+};
+
+const DEFAULT_TOC_TITLE = "On this page";
+
+/** Return the TOC section label for the given BCP-47 language tag. */
+export function getTocTitle(lang?: string): string {
+  if (!lang) return DEFAULT_TOC_TITLE;
+  // "en-US" → try "en" first, then "en-US", then the English default.
+  const primary = lang.split("-")[0]!;
+  return TOC_TITLES[primary] ?? TOC_TITLES[lang] ?? DEFAULT_TOC_TITLE;
+}

package/templates/base/src/components/ai-chat-modal.tsx

@@ -1,3 +1,5 @@
+"use client";
+
 // W6A stub — no-op default export.
 //
 // The host (zudo-doc showcase) ships a full AI-chat modal island here. In

package/templates/base/src/components/doc-history.tsx

@@ -1,3 +1,5 @@
+"use client";
+
 // W6A stub — no-op default + DocHistory named exports.
 //
 // When the docHistory feature is enabled, the feature template

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

@@ -1,3 +1,5 @@
+"use client";
+
 // W6A stub — no-op default + ImageEnlargeSsrFallback named exports.
 //
 // When the imageEnlarge feature is enabled, the feature template

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

@@ -131,8 +131,15 @@ export default function SidebarToggle({
         onClick={() => setOpen(false)}
       />
 
-      {/* Sidebar panel - mobile only (desktop sidebar is in doc-layout) */}
+      {/* Sidebar panel - mobile only (desktop sidebar is in doc-layout).
+          `inert` when closed: the panel is only visually hidden via
+          `-translate-x-full`, so without `inert` its links/filter/buttons
+          stay in the tab order and accessibility tree while off-screen
+          (zudolab/zudo-doc#2059). `inert={false}` serialises to no attribute,
+          so the SSR (open=false → `inert`) and initial client render stay
+          byte-stable for hydration. */}
       <aside
+        inert={!open}
         className={`
           fixed top-[3.5rem] left-0 z-40 h-[calc(100vh-3.5rem)] w-[16rem] flex flex-col
           border-r border-muted bg-bg transition-transform duration-200

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.target.value)}
+            onChange={(e) => setQuery(e.currentTarget.value)}
             className="bg-transparent text-small outline-none w-full text-fg placeholder:text-muted"
           />
         </div>

package/templates/base/zfb-shim.d.ts

@@ -0,0 +1,167 @@
+// Local type shim for the bare `zfb/config` specifier.
+//
+// `@takazudo/zfb` is consumed as a published npm package (version pinned
+// in the root `package.json`). The package exposes its real config types
+// under the *scoped* subpath `@takazudo/zfb/config` → `dist/config.d.ts`.
+// But `zfb.config.ts` imports from the *bare* specifier `zfb/config`,
+// which zfb's build tool aliases to a runtime-only stub at parse time
+// (`zfb-config-stub.mjs` — `defineConfig` is identity, carrying no types).
+// No real file backs `zfb/config` in `node_modules`, so this ambient
+// declaration is what supplies the `ZfbConfig` type to `zfb.config.ts`.
+//
+// IMPORTANT — this block is the source of truth for the type `zfb check`
+// (plain `tsc --noEmit`) binds against the config. An ambient `declare
+// module` wins over node resolution AND over tsconfig `paths`, so it must
+// be kept in sync BY HAND with the published `@takazudo/zfb/config`
+// (`dist/config.d.ts`). When it lags the engine, valid config fields fail
+// `pnpm check` with TS2353 (see Takazudo/zudo-front-builder#678 +
+// zudolab/zudo-doc#1834 — `bundle` was missing here, blocking next.22's
+// `bundle.exclude`).
+
+declare module "zfb/config" {
+  /** JSX framework runtime. */
+  export type Framework = "preact" | "react";
+
+  /** A content collection registered with the zfb engine. */
+  export interface CollectionDef {
+    /** Identifier used at the call site (e.g. `"docs"`). */
+    name: string;
+    /** Directory (relative to the project root) holding the entries. */
+    path: string;
+    /**
+     * Optional schema. Reserved for v1.1 — accepted but not enforced
+     * today. Authored as zod and converted to JSON Schema via
+     * `z.toJSONSchema()` at the boundary.
+     */
+    schema?: Record<string, unknown>;
+  }
+
+  /** Tailwind options; absent = defaults. */
+  export interface TailwindConfig {
+    enabled?: boolean;
+  }
+
+  /** User-supplied plugin configuration entry. */
+  export interface PluginConfig {
+    name: string;
+    options?: Record<string, unknown>;
+  }
+
+  /**
+   * Bundler options. Mirrors `BundleConfig` in crates/zfb/src/config.rs
+   * and the published `@takazudo/zfb/config` (`dist/config.d.ts`). Added
+   * in next.22 (`bundle.exclude`, #664) and extended in next.23
+   * (`mainFields` / `external`, #676).
+   */
+  export interface BundleConfig {
+    /**
+     * Project-relative, gitignore-style globs for source files the bundler
+     * must NOT pull into the esbuild graph (e.g. test fixtures or
+     * `*.stories.tsx`). Matched files are skipped from the shadow-tree walk
+     * and dropped from any eager `import.meta.glob(...)` expansion.
+     */
+    exclude?: string[];
+    /**
+     * Explicit esbuild `main-fields` for the `--platform=neutral` page/SSR
+     * pass (empty by default under `neutral`), letting CJS-`main`-only deps
+     * resolve. Mirrors `BundleConfig::main_fields`.
+     */
+    mainFields?: string[];
+    /**
+     * Bare specifiers to mark external in the `--platform=neutral` pass so
+     * esbuild leaves them unbundled. Mirrors `BundleConfig::external`.
+     */
+    external?: string[];
+  }
+
+  /** Mirrors the Rust `Config` struct one-for-one. */
+  export interface ZfbConfig {
+    outDir?: string;
+    publicDir?: string;
+    host?: string;
+    port?: number;
+    framework?: Framework;
+    collections?: CollectionDef[];
+    tailwind?: TailwindConfig;
+    /**
+     * Bundler options. `bundle.exclude` keeps project-relative globs out of
+     * the esbuild graph — used here to skip `packages/md-plugins/__fixtures__/**`
+     * so the MDX link resolver no longer walks the test fixtures (silences
+     * ~15 pre-existing broken-link warnings). Mirrors `Config::bundle`.
+     */
+    bundle?: BundleConfig;
+    plugins?: PluginConfig[];
+    adapter?: string;
+    /**
+     * Strip `.md` / `.mdx` from in-page `<a href>` paths and append a
+     * trailing `/` so author-written `[label](other.mdx)` references
+     * resolve to the rendered route URL. Mirrors Config::strip_md_ext
+     * in crates/zfb/src/config.rs (zudolab/zfb#131).
+     */
+    stripMdExt?: boolean;
+    /**
+     * Site base path. Prefixed onto stable HTML asset URLs (CSS / JS
+     * `<link>` and `<script>` tags). Normalised to start AND end with
+     * `/`; `undefined` / `""` / `"/"` all behave identically (no
+     * prefix). Mirrors Config::base in crates/zfb/src/config.rs
+     * (Takazudo/zudo-front-builder#154).
+     */
+    base?: string;
+    /**
+     * Configures the syntect-based syntax highlighter shipped with zfb.
+     * Mirrors `code_highlight` in crates/zfb/src/config.rs (Takazudo/zudo-front-builder#188 / sub #194; landed in commit 339e30f).
+     * When omitted, the engine falls back to the hardcoded default theme `base16-ocean.dark`.
+     */
+    codeHighlight?: {
+      theme?: string;
+      themesDir?: string;
+    };
+    /**
+     * Markdown link resolver (port of `remarkResolveMarkdownLinks`).
+     * Mirrors `Config::resolve_markdown_links` in crates/zfb/src/config.rs
+     * (Takazudo/zudo-front-builder PR #234 / zudolab/zudo-doc#1577).
+     * When `enabled: true`, the build appends `ResolveLinksPlugin` to the
+     * mdast pipeline so author-written `[label](./other.mdx)` links are
+     * rewritten to the corresponding rendered route URL — bypassing the
+     * file→directory transformation that breaks relative paths in dist
+     * HTML when `foo.mdx` becomes `foo/index.html`.
+     */
+    resolveMarkdownLinks?: {
+      enabled?: boolean;
+      docsDir?: string;
+      dirs?: Array<{ dir: string; routePrefix: string }>;
+      onBrokenLinks?: "warn" | "error" | "ignore";
+    };
+    /**
+     * Whether the basePath rewriter should append a trailing `/` to
+     * extensionless absolute hrefs. Mirrors `Config::trailing_slash` in
+     * crates/zfb/src/config.rs (Takazudo/zudo-front-builder PR #234 /
+     * zudolab/zudo-doc#1579). Off by default — preserves byte-for-byte
+     * parity with the pre-`trailingSlash` build for projects that
+     * haven't opted in.
+     */
+    trailingSlash?: boolean;
+    /**
+     * Markdown / MDX pipeline options. Mirrors `Config::markdown` →
+     * `MarkdownConfig` in crates/zfb/src/config.rs. zfb next.12 moved the
+     * former-Core features under `markdown.features` and next.13 ships the
+     * rest as opt-in; zudo-doc uses `markdown.features` to opt back into the
+     * former-Core four plus the additional opt-in features (#1804). Each
+     * `features` value is per-feature: `true` for boolean-shorthand features,
+     * or an options object for object-typed features.
+     */
+    markdown?: {
+      gfm?: boolean | Record<string, boolean>;
+      toc?: Record<string, unknown>;
+      externalLinks?: Record<string, unknown>;
+      cjkFriendly?: boolean;
+      features?: Record<string, boolean | Record<string, unknown>>;
+    };
+  }
+
+  /**
+   * Identity helper: returns the supplied config as-is, but typed
+   * against `ZfbConfig`. Use as the default export of `zfb.config.ts`.
+   */
+  export function defineConfig(config: ZfbConfig): ZfbConfig;
+}

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

@@ -1,3 +1,5 @@
+"use client";
+
 import { useState, useEffect, useCallback, useMemo, useRef } from "preact/compat";
 import type { Change } from "diff";
 import type { DocHistoryData, DocHistoryEntry } from "@/types/doc-history";

package/templates/features/docTags/files/pages/lib/_tag-pages.tsx

@@ -131,6 +131,11 @@ export function TagDetailPageView({
       noindex={settings.noindex}
       hideSidebar={true}
       hideToc={true}
+      // Empty fragment suppresses DocLayoutWithDefaults' empty-data default
+      // Sidebar island — its marker never hydrates for published-package
+      // consumers (zfb#999) and zfb >= next.38 warns about it; the sidebar is
+      // hidden on this page anyway (zudolab/zudo-doc#2057).
+      sidebarOverride={<></>}
       // Tag segment URL-encoded — emitted href/path sites only; route params
       // stay raw (e.g. "type:guide" → "type%3Aguide").
       headerOverride={<HeaderWithDefaults lang={locale} currentPath={withBase(`${prefix}/docs/tags/${encodeURIComponent(tag)}`)} />}
@@ -184,6 +189,11 @@ export function TagsIndexPageView({ locale }: { locale: string }): JSX.Element {
       noindex={settings.noindex}
       hideSidebar={true}
       hideToc={true}
+      // Empty fragment suppresses DocLayoutWithDefaults' empty-data default
+      // Sidebar island — its marker never hydrates for published-package
+      // consumers (zfb#999) and zfb >= next.38 warns about it; the sidebar is
+      // hidden on this page anyway (zudolab/zudo-doc#2057).
+      sidebarOverride={<></>}
       headerOverride={<HeaderWithDefaults lang={locale} currentPath={withBase(`${prefix}/docs/tags`)} />}
       breadcrumbOverride={<Breadcrumb items={breadcrumbItems} />}
       footerOverride={<FooterWithDefaults lang={locale} />}

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

@@ -103,6 +103,11 @@ export default function LocaleIndexPage({ params }: PageArgs): JSX.Element {
       noindex={settings.noindex}
       hideSidebar={true}
       hideToc={true}
+      // Empty fragment suppresses DocLayoutWithDefaults' empty-data default
+      // Sidebar island — its marker never hydrates for published-package
+      // consumers (zfb#999) and zfb >= next.38 warns about it; the sidebar is
+      // hidden on this page anyway (zudolab/zudo-doc#2057).
+      sidebarOverride={<></>}
       headerOverride={<HeaderWithDefaults lang={locale as Locale} currentPath={withBase(`/${locale}/`)} />}
       footerOverride={<FooterWithDefaults lang={locale} />}
       bodyEndComponents={<BodyEndIslands basePath={settings.base ?? "/"} />}

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

@@ -1,3 +1,5 @@
+"use client";
+
 import { useState, useEffect, useRef } from "preact/compat";
 import type { JSX } from "preact";
 

package/templates/features/tauri/files/src/components/find-in-page-init.tsx

@@ -1,3 +1,5 @@
+"use client";
+
 import { useState, useEffect, useRef } from "preact/compat";
 import { FindBar } from "./find-bar";
 import { createFindInPage } from "@/utils/find-in-page";
@@ -30,14 +32,18 @@ export default function FindInPageInit() {
     return () => document.removeEventListener("keydown", handler);
   }, [isTauri]);
 
-  // Clear search on zfb page navigation
+  // Clear search on zfb page navigation. zfb navigates via SPA body swap and
+  // fires "zfb:before-preparation" on document before nav — it never fires the
+  // native "pagehide" (full-unload) event. The literal is inlined because
+  // downstream scaffolds do not depend on @takazudo/zudo-doc as a runtime dep
+  // (same reason as the designTokenPanel bootstrap).
   useEffect(() => {
     const handler = () => {
       findInPageRef.current.stop();
       setVisible(false);
     };
-    document.addEventListener("pagehide", handler);
-    return () => document.removeEventListener("pagehide", handler);
+    document.addEventListener("zfb:before-preparation", handler);
+    return () => document.removeEventListener("zfb:before-preparation", handler);
   }, []);
 
   if (!isTauri) return null;

package/templates/features/versioning/files/pages/lib/_versions-page.tsx

@@ -65,6 +65,11 @@ export function VersionsPageView({ locale }: { locale: string }): JSX.Element {
       noindex={settings.noindex}
       hideSidebar={true}
       hideToc={true}
+      // Empty fragment suppresses DocLayoutWithDefaults' empty-data default
+      // Sidebar island — its marker never hydrates for published-package
+      // consumers (zfb#999) and zfb >= next.38 warns about it; the sidebar is
+      // hidden on this page anyway (zudolab/zudo-doc#2057).
+      sidebarOverride={<></>}
       headerOverride={<HeaderWithDefaults lang={locale as Locale} currentPath={withBase(`${prefix}/docs/versions`)} />}
       footerOverride={<FooterWithDefaults lang={locale} />}
       bodyEndComponents={<BodyEndIslands basePath={settings.base ?? "/"} />}