create-zudo-doc 0.2.1 → 0.2.2

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

@@ -278,7 +278,7 @@ function generatePackageJson(choices) {
         // .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.2",
         // 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 +332,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.2";
         // 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.2",
   "description": "Create a new zudo-doc documentation site",
   "license": "MIT",
   "author": "Takeshi Takatsudo",

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
@@ -196,6 +198,7 @@ export function BodyEndIslands({
       <h2 class="sr-only">AI Assistant</h2>
       {aiChat}
       {imageEnlarge}
+      {/* @slot:body-end-islands:extra-islands */}
     </>
   );
 }

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

@@ -45,11 +45,14 @@ 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.
-import { ThemeToggle } from "@takazudo/zudo-doc/theme-toggle";
+// ThemeToggle via the project-source shim (`@/components/theme-toggle`)
+// rather than the package subpath directly. zfb's island scanner does not
+// register "use client" modules under node_modules (zfb#999), so importing
+// the package component here would emit an island marker with no registry
+// entry and the toggle would never hydrate (zudolab/zudo-doc#2048). The shim
+// re-wraps the bare (non-island-wrapped) package ThemeToggle; this wrapper
+// composes its own Island below, avoiding nesting an island inside an island.
+import { ThemeToggle } from "@/components/theme-toggle";
 import SidebarToggle from "@/components/sidebar-toggle";
 import { settings } from "@/config/settings";
 import { defaultLocale, locales, t, type Locale } from "@/config/i18n";

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-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/src/components/theme-toggle.tsx

@@ -0,0 +1,23 @@
+"use client";
+
+// Scanner-visible ThemeToggle shim. zfb's island scanner does not register
+// "use client" modules located under node_modules (Takazudo/zudo-front-builder#999),
+// so importing the package ThemeToggle straight into the server-rendered header
+// emits an island marker with no matching registry entry — the toggle renders
+// but never hydrates, on every page (zudolab/zudo-doc#2048). This thin
+// project-source wrapper gives the scanner a local binding to register; it
+// re-wraps the bare (non-island-wrapped) package component unchanged.
+import type { JSX } from "preact";
+import {
+  ThemeToggle as ZudoDocThemeToggle,
+  type ThemeToggleProps,
+} from "@takazudo/zudo-doc/theme-toggle";
+
+export function ThemeToggle(props: ThemeToggleProps): JSX.Element {
+  return <ZudoDocThemeToggle {...props} />;
+}
+ThemeToggle.displayName = "ThemeToggle";
+
+export type { ThemeToggleProps };
+
+export default ThemeToggle;

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/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;