create-zudo-doc 0.2.0 → 0.2.2

package/templates/base/pages/lib/_nav-data-prep.ts

@@ -0,0 +1,137 @@
+// Shared nav data-prep utilities used by both _header-with-defaults.tsx
+// and _sidebar-with-defaults.tsx.
+//
+// Extracted to avoid maintaining four near-identical copies: the two host
+// modules above plus their template mirrors under
+// packages/create-zudo-doc/templates/base/pages/lib/.
+
+import { settings } from "@/config/settings";
+import { t, type Locale } from "@/config/i18n";
+import {
+  buildLocaleLinks,
+  navHref,
+  versionedDocsUrl,
+} from "@/utils/base";
+import { type NavNode } from "@/utils/docs";
+import { buildSidebarForSection } from "@/utils/sidebar";
+import { loadNavSourceDocs } from "./_nav-source-docs";
+
+// ---------------------------------------------------------------------------
+// remapVersionedHrefs
+// ---------------------------------------------------------------------------
+
+/**
+ * Walk the nav tree and rewrite each node's `href` to its versioned form.
+ *
+ * `buildNavTree` always emits hrefs via `docsUrl()`; when the active route
+ * lives under `/v/{version}/...` we need the same nodes pointing at the
+ * versioned URL so internal nav clicks stay inside the version. Skips
+ * nodes without an href (link-only or category placeholders).
+ */
+export function remapVersionedHrefs(
+  nodes: NavNode[],
+  version: string,
+  nodeLang: Locale,
+): NavNode[] {
+  return nodes.map((node) => {
+    const children =
+      node.children.length > 0
+        ? remapVersionedHrefs(node.children, version, nodeLang)
+        : node.children;
+
+    if (!node.href || node.slug.startsWith("__link__")) {
+      return children !== node.children ? { ...node, children } : node;
+    }
+
+    const newHref = versionedDocsUrl(node.slug, version, nodeLang);
+    return { ...node, href: newHref, children };
+  });
+}
+
+// ---------------------------------------------------------------------------
+// buildRootMenuItems
+// ---------------------------------------------------------------------------
+
+/**
+ * Root-menu items derived from settings.headerNav (mobile "back to menu" list).
+ *
+ * Used by both header and sidebar wrappers — the same nav data feeds both the
+ * mobile SidebarToggle (header) and the desktop SidebarTree (sidebar).
+ */
+export function buildRootMenuItems(
+  lang: Locale,
+  currentVersion?: string,
+) {
+  return settings.headerNav.map((item) => ({
+    label: item.labelKey
+      ? t(item.labelKey as Parameters<typeof t>[0], lang)
+      : item.label,
+    href: navHref(item.path, lang, currentVersion),
+    children: item.children?.map((child) => ({
+      label: child.labelKey
+        ? t(child.labelKey as Parameters<typeof t>[0], lang)
+        : child.label,
+      href: navHref(child.path, lang, currentVersion),
+    })),
+  }));
+}
+
+// ---------------------------------------------------------------------------
+// buildLocaleLinksForNav
+// ---------------------------------------------------------------------------
+
+/**
+ * Locale-switcher links for the mobile sidebar footer and language switcher.
+ * Returns `undefined` when only one locale is configured (single-locale guard).
+ */
+export function buildLocaleLinksForNav(
+  currentPath: string,
+  lang: Locale,
+  localeCount: number,
+) {
+  return localeCount > 1 ? buildLocaleLinks(currentPath, lang) : undefined;
+}
+
+// ---------------------------------------------------------------------------
+// buildSidebarNodes
+// ---------------------------------------------------------------------------
+
+/**
+ * Build the resolved sidebar node list for a given section + version.
+ *
+ * Loads the nav source, filters to the active section, then optionally
+ * remaps hrefs for versioned routes.
+ *
+ * `emptyWhenUnsectioned` controls the `navSection === undefined` case —
+ * the two legacy call sites deliberately disagreed: the header's mobile
+ * drawer returned `[]` (root menu only), while the desktop sidebar fell
+ * through to `buildSidebarForSection(..., undefined)` = the FULL tree
+ * (pages whose slug matches no headerNav categoryMatch still get a
+ * sidebar). Collapsing both to `[]` shipped an empty desktop sidebar for
+ * unsectioned pages — keep the divergence explicit here.
+ */
+export function buildSidebarNodes(
+  lang: Locale,
+  navSection: string | undefined,
+  currentVersion?: string,
+  emptyWhenUnsectioned = true,
+): NavNode[] {
+  if (navSection === undefined && emptyWhenUnsectioned) return [];
+  const { navDocs, categoryMeta } = loadNavSourceDocs(lang, currentVersion);
+  const rawNodes = buildSidebarForSection(navDocs, lang, navSection, categoryMeta);
+  return currentVersion
+    ? remapVersionedHrefs(rawNodes, currentVersion, lang)
+    : rawNodes;
+}
+
+// ---------------------------------------------------------------------------
+// themeDefaultMode
+// ---------------------------------------------------------------------------
+
+/**
+ * Extract the configured default color mode from settings.
+ * Returns `undefined` when color mode is not configured (single-scheme projects).
+ */
+export function getThemeDefaultMode() {
+  return settings.colorMode ? settings.colorMode.defaultMode : undefined;
+}

package/templates/base/pages/lib/_nav-source-docs.ts

@@ -21,7 +21,7 @@
 //   - route-enumerators.ts (sitemap) and the MDX nav wrappers
 // each picking the `NavSourceVariant` matching its filter needs.
 
-import { defaultLocale, type Locale } from "@/config/i18n";
+import { defaultLocale, getLocaleConfig, type Locale } from "@/config/i18n";
 import { settings } from "@/config/settings";
 import {
   loadCategoryMeta,
@@ -84,7 +84,7 @@ export type NavSourceDocs = {
   categoryMeta: Map<string, CategoryMeta>;
   /** Slugs that came from the locale collection (for isFallback). Empty for
    *  default-locale / single-collection cases. */
-  localeSlugSet: Set<string>;
+  localeSlugSet: ReadonlySet<string>;
 };
 
 /**
@@ -124,7 +124,11 @@ export function resolveNavSource(
   //     pages in sync. Otherwise (default locale, or the version not configured
   //     for this locale) fall back to the version's EN base collection.
   if (currentVersion) {
-    const versionConfig = settings.versions?.find((v) => v.slug === currentVersion);
+    // `versions` is `VersionConfig[] | false` — `false?.find` would throw
+    // (optional chaining only short-circuits on null/undefined).
+    const versionConfig = Array.isArray(settings.versions)
+      ? settings.versions.find((v) => v.slug === currentVersion)
+      : undefined;
     const localeDir = versionConfig?.locales?.[lang]?.dir;
     if (lang !== defaultLocale && localeDir) {
       return resolveVersionedLocaleSource(
@@ -138,7 +142,7 @@ export function resolveNavSource(
     const docs = stableDocs(`docs-v-${currentVersion}`);
     const categoryMeta = loadCategoryMeta(versionConfig?.docsDir ?? settings.docsDir);
     const navDocs = stableNavDocs(docs);
-    return { docs, navDocs, categoryMeta, localeSlugSet: EMPTY_SLUG_SET as Set<string> };
+    return { docs, navDocs, categoryMeta, localeSlugSet: EMPTY_SLUG_SET };
   }
 
   // --- Default locale: the "docs" collection directly.
@@ -146,7 +150,7 @@ export function resolveNavSource(
     const docs = stableDocs("docs");
     const categoryMeta = loadCategoryMeta(settings.docsDir);
     const navDocs = stableNavDocs(docs);
-    return { docs, navDocs, categoryMeta, localeSlugSet: EMPTY_SLUG_SET as Set<string> };
+    return { docs, navDocs, categoryMeta, localeSlugSet: EMPTY_SLUG_SET };
   }
 
   // --- Non-default locale: locale-first merge with EN fallback.
@@ -163,7 +167,7 @@ export function resolveNavSource(
   );
   const docs = merged.docs;
 
-  const localeDir = settings.locales[lang]?.dir ?? settings.docsDir;
+  const localeDir = getLocaleConfig(lang)?.dir ?? settings.docsDir;
   const categoryMeta = stableMergeCategoryMeta(settings.docsDir, localeDir);
   const navDocs = stableNavDocs(docs);
 

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

@@ -41,20 +41,35 @@ export const SEARCH_WIDGET_SCRIPT = /* javascript */ `(function () {
     return query.trim().split(/\\s+/).filter(Boolean);
   }
 
+  // scoreEntry reads pre-lowercased fields (_titleLc, _descLc, _bodyLc)
+  // set by prepareLc() at index-load time. Terms arrive already lowercased
+  // from search() so no per-call toLowerCase() is needed.
   function scoreEntry(entry, terms) {
     var score = 0;
-    var titleLower = (entry.title || "").toLowerCase();
-    var bodyLower = (entry.body || "").toLowerCase();
-    var descLower = (entry.description || "").toLowerCase();
+    var titleLc = entry._titleLc;
+    var descLc  = entry._descLc;
+    var bodyLc  = entry._bodyLc;
     for (var i = 0; i < terms.length; i++) {
-      var t = terms[i].toLowerCase();
-      if (titleLower.indexOf(t) !== -1) score += 3;
-      if (descLower.indexOf(t) !== -1) score += 2;
-      if (bodyLower.indexOf(t) !== -1) score += 1;
+      var t = terms[i];
+      if (titleLc.indexOf(t) !== -1) score += 3;
+      if (descLc.indexOf(t) !== -1)  score += 2;
+      if (bodyLc.indexOf(t) !== -1)  score += 1;
     }
     return score;
   }
 
+  // Pre-lowercase the searched fields on each entry once at load time so that
+  // scoreEntry() does not re-lowercase the entire ~162 KB index on every
+  // debounced keystroke.  Original-case fields are preserved for display.
+  function prepareLc(entries) {
+    for (var i = 0; i < entries.length; i++) {
+      var e = entries[i];
+      e._titleLc = (e.title       || "").toLowerCase();
+      e._descLc  = (e.description || "").toLowerCase();
+      e._bodyLc  = (e.body        || "").toLowerCase();
+    }
+  }
+
   function highlightTerms(text, terms) {
     if (!terms.length) return escapeHtml(text);
     var escaped = terms.map(function(t) { return escapeRegExp(t); });
@@ -99,6 +114,7 @@ export const SEARCH_WIDGET_SCRIPT = /* javascript */ `(function () {
       this._countNarrow = null;
       this._entries = null;
       this._loading = false;
+      this._indexUnavailable = false;
       this._debounce = null;
       this._currentQuery = "";
       this._allResults = [];
@@ -231,6 +247,7 @@ export const SEARCH_WIDGET_SCRIPT = /* javascript */ `(function () {
         })
         .then(function(data) {
           self._entries = Array.isArray(data) ? data : (data.entries || []);
+          prepareLc(self._entries);
           self._loading = false;
           // If user already typed, search now
           if (self._input && self._input.value.trim()) {
@@ -239,7 +256,10 @@ export const SEARCH_WIDGET_SCRIPT = /* javascript */ `(function () {
         })
         .catch(function() {
           self._loading = false;
-          // Index unavailable — silently degrade
+          self._indexUnavailable = true;
+          if (self._results) {
+            self._results.innerHTML = "<p class=\\"text-small text-muted\\">Search unavailable</p>";
+          }
         });
     }
 
@@ -264,7 +284,10 @@ export const SEARCH_WIDGET_SCRIPT = /* javascript */ `(function () {
         return;
       }
 
-      var terms = parseTerms(query);
+      // Lowercase the query terms once here so scoreEntry() can do plain
+      // indexOf() against pre-lowercased entry fields without repeating
+      // toLowerCase() across the entire index on every keystroke.
+      var terms = parseTerms(query).map(function(t) { return t.toLowerCase(); });
       var scored = [];
       for (var i = 0; i < this._entries.length; i++) {
         var s = scoreEntry(this._entries[i], terms);

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

@@ -35,14 +35,13 @@ import type { JSX } from "preact";
 // reaches the rendered tree).
 import { Island } from "@takazudo/zfb";
 import SidebarTree from "@/components/sidebar-tree";
-import { settings } from "@/config/settings";
 import { defaultLocale, locales, t, type Locale } from "@/config/i18n";
-import { buildLocaleLinks, navHref, versionedDocsUrl } from "@/utils/base";
 import {
-  type NavNode,
-} from "@/utils/docs";
-import { buildSidebarForSection } from "@/utils/sidebar";
-import { loadNavSourceDocs } from "./_nav-source-docs";
+  buildRootMenuItems,
+  buildLocaleLinksForNav,
+  buildSidebarNodes,
+  getThemeDefaultMode,
+} from "./_nav-data-prep";
 
 export interface SidebarWithDefaultsProps {
   /** Slug of the active doc page, used to highlight the current entry. */
@@ -61,34 +60,6 @@ export interface SidebarWithDefaultsProps {
   currentPath?: string;
 }
 
-/**
- * Walk the nav tree and rewrite each node's `href` to its versioned form.
- *
- * `buildNavTree` always emits hrefs via `docsUrl()`; when the active route
- * lives under `/v/{version}/...` we need the same nodes pointing at the
- * versioned URL so internal nav clicks stay inside the version. Skips
- * nodes without an href (link-only or category placeholders).
- */
-function remapVersionedHrefs(
-  nodes: NavNode[],
-  version: string,
-  nodeLang: Locale,
-): NavNode[] {
-  return nodes.map((node) => {
-    const children =
-      node.children.length > 0
-        ? remapVersionedHrefs(node.children, version, nodeLang)
-        : node.children;
-
-    if (!node.href || node.slug.startsWith("__link__")) {
-      return children !== node.children ? { ...node, children } : node;
-    }
-
-    const newHref = versionedDocsUrl(node.slug, version, nodeLang);
-    return { ...node, href: newHref, children };
-  });
-}
-
 /**
  * Default-bearing host wrapper that performs sidebar data prep, then wraps
  * the project's `<SidebarTree>`
@@ -117,35 +88,21 @@ export function SidebarWithDefaults(
     currentPath = "",
   } = props;
 
-  // Root-menu items derived from headerNav (mobile back-to-menu list).
-  // The Astro template fed labelKey through `t(...)` and computed hrefs
-  // with `navHref()`; mirror that exactly so the rendered list stays
-  // identical between the A and B sites.
-  const rootMenuItems = settings.headerNav.map((item) => ({
-    label: item.labelKey
-      ? t(item.labelKey as Parameters<typeof t>[0], lang)
-      : item.label,
-    href: navHref(item.path, lang, currentVersion),
-    children: item.children?.map((child) => ({
-      label: child.labelKey
-        ? t(child.labelKey as Parameters<typeof t>[0], lang)
-        : child.label,
-      href: navHref(child.path, lang, currentVersion),
-    })),
-  }));
+  // Root-menu items, sidebar nodes, locale links, and theme mode — all
+  // delegated to the shared _nav-data-prep helpers so header and sidebar
+  // wrappers stay in sync without duplicating the logic.
+  const rootMenuItems = buildRootMenuItems(lang, currentVersion);
 
   const backToMenuLabel = navSection ? t("nav.backToMenu", lang) : undefined;
 
-  const { navDocs, categoryMeta } = loadNavSourceDocs(lang, currentVersion);
-  const rawNodes = buildSidebarForSection(navDocs, lang, navSection, categoryMeta);
-  const nodes = currentVersion
-    ? remapVersionedHrefs(rawNodes, currentVersion, lang)
-    : rawNodes;
+  // emptyWhenUnsectioned=false: the desktop sidebar falls back to the FULL
+  // tree for pages whose slug matches no headerNav categoryMatch (legacy
+  // behavior) — only the header's mobile drawer collapses to root menu.
+  const nodes = buildSidebarNodes(lang, navSection, currentVersion, false);
 
   // Locale-switcher links are only meaningful when more than one locale is
   // configured — matches the Astro template's guard.
-  const localeLinks =
-    locales.length > 1 ? buildLocaleLinks(currentPath, lang) : undefined;
+  const localeLinks = buildLocaleLinksForNav(currentPath, lang, locales.length);
 
   // Wrap <SidebarTree> directly in <Island when="load">. SSR emits the
   // `data-zfb-island="SidebarTree"` marker around the rendered tree, with
@@ -164,9 +121,7 @@ export function SidebarWithDefaults(
         rootMenuItems={rootMenuItems}
         backToMenuLabel={backToMenuLabel}
         localeLinks={localeLinks}
-        themeDefaultMode={
-          settings.colorMode ? settings.colorMode.defaultMode : undefined
-        }
+        themeDefaultMode={getThemeDefaultMode()}
       />
     ),
   }) as unknown as JSX.Element;

package/templates/base/pages/lib/locale-merge.ts

@@ -94,7 +94,7 @@ export interface MergeLocaleDocsResult<T extends DocsEntry = DocsEntry> {
    * Useful for callers that need to determine whether a page is a fallback
    * (i.e. `isFallback = !localeSlugSet.has(slug)`).
    */
-  localeSlugSet: Set<string>;
+  localeSlugSet: ReadonlySet<string>;
 }
 
 /**

package/templates/base/pages/lib/route-enumerators.ts

@@ -71,10 +71,10 @@ export function enumerateDocsRoutes(locale: string): string[] {
     // safety re-application of the same rule (idempotent on the already-
     // stripped id); kept so this enumerator's slug derivation reads as a
     // single explicit call to the canonical helper.
-    urls.push(docsUrl(doc.data.slug ?? toRouteSlug(doc.id), locale as string));
+    urls.push(docsUrl(doc.data.slug ?? toRouteSlug(doc.id), locale as Locale));
   }
   for (const node of collectAutoIndexNodes(tree)) {
-    urls.push(docsUrl(node.slug, locale as string));
+    urls.push(docsUrl(node.slug, locale as Locale));
   }
 
   return [...new Set(urls)];
@@ -127,10 +127,14 @@ export function enumerateTagsRoutes(locale: string): string[] {
   const tagMap = collectTags(docs, (id, data) => data.slug ?? toRouteSlug(id));
 
   for (const tag of tagMap.keys()) {
+    // Tag segment URL-encoded — these URLs feed the sitemap, which must
+    // carry well-formed encoded URLs (e.g. "type:guide" → "type%3Aguide").
+    // Route params (the page paths() functions) stay raw.
+    const encoded = encodeURIComponent(tag);
     const tagPath =
       locale === defaultLocale
-        ? `/docs/tags/${tag}`
-        : `/${locale}/docs/tags/${tag}`;
+        ? `/docs/tags/${encoded}`
+        : `/${locale}/docs/tags/${encoded}`;
     urls.push(withBase(tagPath));
   }
 
@@ -194,10 +198,10 @@ export function enumerateVersionedRoutes(
       // category_no_page index.mdx → no route, no sitemap URL (see paths()).
       if (doc.data.category_no_page === true) continue;
       const slug = doc.data.slug ?? toRouteSlug(doc.id);
-      urls.push(versionedDocsUrl(slug, version.slug, locale as string));
+      urls.push(versionedDocsUrl(slug, version.slug, locale as Locale));
     }
     for (const node of collectAutoIndexNodes(tree)) {
-      urls.push(versionedDocsUrl(node.slug, version.slug, locale as string));
+      urls.push(versionedDocsUrl(node.slug, version.slug, locale as Locale));
     }
   }
 
@@ -222,7 +226,7 @@ export function enumerateVersionedRoutes(
  * slash). The sitemap renderer prefixes each with settings.siteUrl.
  */
 export function enumerateAllRoutes(): Map<string, string> {
-  const today = new Date().toISOString().split("T")[0];
+  const today = new Date().toISOString().split("T")[0] ?? "";
   const routes = new Map<string, string>();
 
   function add(url: string): void {

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

@@ -1,3 +1,4 @@
+// @ts-check
 // Adapter from Connect-style middleware (`(req, res, next) => void`) to
 // the request-response shape zfb's `devMiddleware` lifecycle hook
 // expects (`(req: ZfbDevMiddlewareRequest) => Promise<ZfbDevMiddlewareResponse | undefined>`).
@@ -16,8 +17,19 @@
 // the v2 integration package keeps its Connect-style API surface so
 // non-zfb embedders (Astro, plain Vite, a unit test) continue to work.
 
+/** @import { ZfbDevMiddlewareRequest, ZfbDevMiddlewareResponse } from "@takazudo/zfb/plugins" */
+
 import { Buffer } from "node:buffer";
 
+/**
+ * Connect-style middleware: `(req, res, next) => void`.
+ * The req/res parameters are typed as `any` here because this adapter
+ * intentionally passes a plain-object shim that structurally satisfies the
+ * subset of `IncomingMessage` / `ServerResponse` that the v2 integration
+ * middlewares actually access — not the full Node.js types.
+ * @typedef {(req: any, res: any, next: (err?: unknown) => void) => void} ConnectMiddleware
+ */
+
 /**
  * Convert a Connect-style middleware to a zfb devMiddleware handler.
  * The returned async function takes a `ZfbDevMiddlewareRequest` and
@@ -37,6 +49,9 @@ import { Buffer } from "node:buffer";
  *   - Binary bodies (Buffer / Uint8Array) → encoded as base64 and
  *     flagged `bodyEncoding: "base64"` so the JSON envelope round-trip
  *     stays loss-less.
+ *
+ * @param {ConnectMiddleware} middleware
+ * @returns {(zfbReq: ZfbDevMiddlewareRequest) => Promise<ZfbDevMiddlewareResponse | undefined>}
  */
 export function connectToZfbHandler(middleware) {
   return (zfbReq) => {
@@ -57,9 +72,14 @@ export function connectToZfbHandler(middleware) {
       // today (`statusCode`, `setHeader`, `getHeader`, `end`) — extend
       // here if a future middleware needs more.
       let statusCode = 200;
+      /** @type {Record<string, string>} */
       const headers = {};
       let settled = false;
 
+      /**
+       * @param {string | Buffer | Uint8Array | null | undefined} body
+       * @returns {void}
+       */
       const finish = (body) => {
         if (settled) return;
         settled = true;
@@ -67,6 +87,7 @@ export function connectToZfbHandler(middleware) {
         // axum's expectation (`Record<string, string>` of arbitrary
         // case). Last-wins on collision; with `setHeader` callers this
         // shouldn't happen.
+        /** @type {Record<string, string>} */
         const normalisedHeaders = {};
         for (const [k, v] of Object.entries(headers)) {
           normalisedHeaders[k.toLowerCase()] = String(v);
@@ -93,12 +114,18 @@ export function connectToZfbHandler(middleware) {
         get statusCode() {
           return statusCode;
         },
+        /** @param {number} v */
         set statusCode(v) {
           statusCode = v;
         },
+        /**
+         * @param {string} name
+         * @param {string | number | readonly string[]} value
+         */
         setHeader(name, value) {
-          headers[name] = value;
+          headers[name] = String(value);
         },
+        /** @param {string} name */
         getHeader(name) {
           // Header lookup is case-insensitive in Node's real
           // ServerResponse — mirror that so middlewares that probe an
@@ -113,11 +140,13 @@ export function connectToZfbHandler(middleware) {
         get headersSent() {
           return settled;
         },
+        /** @param {string | Buffer | Uint8Array | null | undefined} [body] */
         end(body) {
           finish(body);
         },
       };
 
+      /** @param {unknown} [err] */
       const next = (err) => {
         if (settled) return;
         if (err) {

package/templates/base/plugins/copy-public-plugin.mjs

@@ -1,3 +1,4 @@
+// @ts-check
 // zfb plugin module: copy-public.
 //
 // Workaround for upstream zfb gap — `zfb build` does not copy `public/`
@@ -21,15 +22,22 @@
 // `zfb.config.ts`. The `base` option is intentionally unused — see
 // rationale above.
 
+/** @import { ZfbBuildHookContext, ZfbPlugin } from "@takazudo/zfb/plugins" */
+
 import { cp } from "node:fs/promises";
 import { resolve } from "node:path";
 
+/** @type {ZfbPlugin} */
 export default {
   name: "copy-public",
 
+  /** @param {ZfbBuildHookContext} ctx */
   async postBuild(ctx) {
     const { publicDir: publicDirOption } = ctx.options;
-    const publicDir = resolve(ctx.projectRoot, publicDirOption ?? "public");
+    const publicDir = resolve(
+      ctx.projectRoot,
+      typeof publicDirOption === "string" ? publicDirOption : "public",
+    );
     const dest = ctx.outDir;
 
     ctx.logger.info(`copying ${publicDir} → ${dest}`);
@@ -38,7 +46,7 @@ export default {
       recursive: true,
       force: true,
       errorOnExist: false,
-    }).catch((err) => {
+    }).catch((/** @type {NodeJS.ErrnoException} */ err) => {
       if (err.code === "ENOENT") {
         // publicDir does not exist or is empty — treat as no-op.
         ctx.logger.info("public/ not found — skipping copy");

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

@@ -1,3 +1,4 @@
+// @ts-check
 // zfb plugin module: search-index.
 //
 // Wires two lifecycle hooks for the search-index integration:
@@ -16,25 +17,30 @@
 // Inline functions are not supported by zfb's plugin runtime; see the
 // sibling `doc-history-plugin.mjs` for the rationale.
 
+/** @import { ZfbBuildHookContext, ZfbDevMiddlewareContext, ZfbPlugin } from "@takazudo/zfb/plugins" */
+/** @import { SearchIndexBuildOptions, SearchIndexConfig } from "@takazudo/zudo-doc/integrations/search-index" */
+
 import { emitSearchIndex, createSearchIndexDevMiddleware } from "@takazudo/zudo-doc/integrations/search-index";
 import { connectToZfbHandler } from "./connect-adapter.mjs";
 
+/** @type {ZfbPlugin} */
 export default {
   name: "search-index",
 
+  /** @param {ZfbBuildHookContext} ctx */
   postBuild(ctx) {
-    const { docsDir, locales, base } = ctx.options;
-    emitSearchIndex({
+    emitSearchIndex(/** @type {SearchIndexBuildOptions} */ (/** @type {unknown} */ ({
+      ...ctx.options,
       outDir: ctx.outDir,
-      docsDir,
-      locales,
-      base,
       logger: ctx.logger,
-    });
+    })));
   },
 
+  /** @param {ZfbDevMiddlewareContext} ctx */
   devMiddleware(ctx) {
-    const middleware = createSearchIndexDevMiddleware(ctx.options);
+    const middleware = createSearchIndexDevMiddleware(
+      /** @type {SearchIndexConfig} */ (/** @type {unknown} */ (ctx.options)),
+    );
     // zfb's `register(path, handler)` matches against the FULL request
     // URL (no base-stripping). For a non-root base (e.g. "/my-docs/"),
     // requests arrive as `/my-docs/search-index.json`, so we register
@@ -43,11 +49,17 @@ export default {
     // middleware itself is base-tolerant (matches via
     // `endsWith("/search-index.json")`), so it does not need a
     // separate base-stripping pass.
-    const basePrefix = stripTrailingSlash(ctx.options.base ?? "");
+    const basePrefix = stripTrailingSlash(
+      typeof ctx.options["base"] === "string" ? ctx.options["base"] : "",
+    );
     ctx.register(`${basePrefix}/search-index.json`, connectToZfbHandler(middleware));
   },
 };
 
+/**
+ * @param {string} s
+ * @returns {string}
+ */
 function stripTrailingSlash(s) {
   if (typeof s !== "string" || s.length === 0) return "";
   return s.endsWith("/") ? s.slice(0, -1) : s;

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

@@ -3,7 +3,7 @@
 // Use preact hook entrypoints directly — the "react" → "preact/compat" alias
 // lets us consume React-typed components in this Preact app (configured
 // project-wide). Same pattern as src/components/sidebar-tree.tsx and
-// packages/zudo-doc/src/theme/theme-toggle.tsx. Type references via
+// packages/zudo-doc/src/theme-toggle/index.tsx. Type references via
 // the global React namespace still resolve via @types/react.
 import { useState, useEffect } from "preact/hooks";
 import clsx from "clsx";