create-zudo-doc 0.2.0 → 0.2.1

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

@@ -30,8 +30,8 @@ import { defaultLocale } from "@/config/i18n";
 import { tagVocabulary } from "@/config/tag-vocabulary";
 import { collectTags } from "@/utils/tags";
 import { toRouteSlug } from "@/utils/slug";
-import { loadDocs } from "../_data";
 import { mergeLocaleDocs } from "./locale-merge";
+import { stableDocs, memoizeDerived } from "./_nav-source-cache";
 import type { DocsEntry } from "@/types/docs-entry";
 
 // ---------------------------------------------------------------------------
@@ -51,12 +51,18 @@ function localizeHref(href: string, lang: string): string {
   return resolveHref(href);
 }
 
-/** Build the base-prefixed tag detail page href for the given locale. */
+/**
+ * Build the base-prefixed tag detail page href for the given locale.
+ * The tag segment is URL-encoded at the href site only — route params stay
+ * raw, so the built output dir keeps the raw tag name and the server decodes
+ * the percent-encoded href back to it (e.g. "type:guide" → "type%3Aguide").
+ */
 function tagHref(tag: string, lang: string): string {
+  const encoded = encodeURIComponent(tag);
   const path =
     lang === defaultLocale
-      ? `/docs/tags/${tag}`
-      : `/${lang}/docs/tags/${tag}`;
+      ? `/docs/tags/${encoded}`
+      : `/${lang}/docs/tags/${encoded}`;
   return withBase(path);
 }
 
@@ -110,15 +116,22 @@ export function FooterWithDefaults({
   let tagColumns: FooterTagColumn[] = [];
 
   if (taglist?.enabled) {
-    // Load docs synchronously (zfb ADR-004 — synchronous content snapshot).
-    let docs: DocsEntry[];
-    if (lang === defaultLocale) {
-      // category_no_page index files build no route — drop them so the footer
-      // taglist matches the tag-route pages (which all now filter too).
-      docs = loadDocs("docs").filter(
-        (d) => !d.data.draft && !d.data.unlisted && !d.data.category_no_page,
-      );
-    } else {
+    // Memoize docs loading and tag aggregation on the snapshot-anchored stable
+    // docs identity — same pattern as _nav-source-cache — so this block runs
+    // once per locale per build, not once per page render.
+    const allTags = (() => {
+      if (lang === defaultLocale) {
+        const baseDocs = stableDocs("docs");
+        return memoizeDerived([baseDocs], "footerTaglist;default", () => {
+          // category_no_page index files build no route — drop them so the
+          // footer taglist matches the tag-route pages (which all now filter too).
+          const docs: DocsEntry[] = baseDocs.filter(
+            (d) => !d.data.draft && !d.data.unlisted && !d.data.category_no_page,
+          );
+          const tagMap = collectTags(docs, (id, data) => data.slug ?? toRouteSlug(id));
+          return [...tagMap.values()].sort((a, b) => a.tag.localeCompare(b.tag, lang));
+        });
+      }
       // Apply the default-locale-only filter so the footer taglist only counts
       // tags that have a locale-routable tag page — matching the tag-route
       // pages ([tag].tsx / tags/index.tsx) and enumerateTagsRoutes, which all
@@ -127,21 +140,19 @@ export function FooterWithDefaults({
       // prefix pages. category_no_page is dropped for the same reason — AFTER
       // the merge, so a locale override carrying the flag first wins the merge
       // (pre-merge filtering would let the unflagged base doc resurface).
-      const result = mergeLocaleDocs({
-        baseDocs: loadDocs("docs").filter((d) => !d.data.draft),
-        localeDocs: loadDocs(`docs-${lang}`).filter((d) => !d.data.draft),
-        applyDefaultLocaleOnlyFilter: true,
+      const baseDocs = stableDocs("docs");
+      const localeDocs = stableDocs(`docs-${lang}`);
+      return memoizeDerived([baseDocs, localeDocs], `footerTaglist;${lang}`, () => {
+        const result = mergeLocaleDocs({
+          baseDocs: baseDocs.filter((d) => !d.data.draft),
+          localeDocs: localeDocs.filter((d) => !d.data.draft),
+          applyDefaultLocaleOnlyFilter: true,
+        });
+        const docs: DocsEntry[] = result.docs.filter((d) => !d.data.category_no_page);
+        const tagMap = collectTags(docs, (id, data) => data.slug ?? toRouteSlug(id));
+        return [...tagMap.values()].sort((a, b) => a.tag.localeCompare(b.tag, lang));
       });
-      docs = result.docs.filter((d) => !d.data.category_no_page);
-    }
-
-    const tagMap = collectTags(
-      docs,
-      (id, data) => data.slug ?? toRouteSlug(id),
-    );
-    const allTags = [...tagMap.values()].sort((a, b) =>
-      a.tag.localeCompare(b.tag, lang),
-    );
+    })();
 
     const vocabularyActive =
       Boolean(settings.tagVocabulary) && settings.tagGovernance !== "off";

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

@@ -20,16 +20,13 @@
 
 import type { JSX } from "preact";
 import { OgTags, TwitterCard } from "@takazudo/zudo-doc/head";
-// Inlined from @takazudo/zudo-doc sidebar-resizer-init.tsx (SIDEBAR_RESIZER_RESTORE_SCRIPT) — the published 0.1.0 dist doesn't export it yet; keep in sync if the clamp bounds [192,448] change.
-const SIDEBAR_RESIZER_RESTORE_SCRIPT = `(function(){try{var w=localStorage.getItem("zudo-doc-sidebar-width");if(!w)return;var n=parseFloat(w);if(!isFinite(n))return;if(n<192)n=192;else if(n>448)n=448;document.documentElement.style.setProperty("--zd-sidebar-w",n+"px");}catch(e){}})();`;
-// Don't import ColorSchemeProvider from "@takazudo/zudo-doc/theme" — that
-// barrel also re-exports DesignTokenTweakPanel + ColorTweakExportModal, which
-// transitively pull `src/components/design-token-tweak/*` and the v2 panel
-// modules (and react-dependent code) into the zfb esbuild graph. Same hazard
-// the host's `_header-with-defaults.tsx` documents for ThemeToggle. The v2
-// package exposes a dedicated `./theme/color-scheme-provider` subpath whose
-// only output is the SSR-only ColorSchemeProvider component, keeping this
-// head emission free of the panel-module dependency chain.
+import { SIDEBAR_RESIZER_RESTORE_SCRIPT } from "@takazudo/zudo-doc/sidebar-resizer";
+// Import ColorSchemeProvider from the dedicated
+// `./theme/color-scheme-provider` subpath rather than the
+// "@takazudo/zudo-doc/theme" barrel — the barrel also re-exports the
+// ColorTweakExportModal island and the design-token SerDe/iframe-bridge
+// modules, which this SSR-only head emission does not need in its zfb
+// esbuild graph.
 import ColorSchemeProvider from "@takazudo/zudo-doc/theme/color-scheme-provider";
 import { composeMetaTitle } from "./_compose-meta-title";
 import { withBase, absoluteUrl } from "@/utils/base";

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

@@ -25,8 +25,8 @@
 //     hides it on pages with hide_sidebar). When `navSection` is defined the
 //     panel gets the full section tree; when undefined (home, 404, tags,
 //     versions) nodes=[] so the panel shows only rootMenuItems.
-//   - ThemeToggle from the package (self-island-wrapped) is always passed to
-//     Header.themeToggle so the ThemeToggle island marker appears in the
+//   - The bare package ThemeToggle (wrapped in Island below) is always passed
+//     to Header.themeToggle so the ThemeToggle island marker appears in the
 //     header on every page — matching the documented header contract.
 //
 // Locale switcher strategy (refs #1453):
@@ -45,68 +45,30 @@ import {
   VersionSwitcher,
   type VersionSwitcherLabels,
 } from "@takazudo/zudo-doc/i18n-version";
-// Don't import ThemeToggle from "@takazudo/zudo-doc/theme" — that barrel
-// also re-exports DesignTokenTweakPanel and ColorTweakExportModal, which
-// transitively pull `src/components/design-token-tweak/*` and the v2 panel
-// modules into the zfb esbuild graph. Those files import `react`, which
-// zfb does not alias to `preact/compat`, so the build fails. Use the host's
-// local ThemeToggle (already on `preact/hooks`) and wrap it in Island here
-// so the SSG output still emits the `data-zfb-island="ThemeToggle"` marker.
-import ThemeToggle from "@/components/theme-toggle";
+// 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";
 import SidebarToggle from "@/components/sidebar-toggle";
 import { settings } from "@/config/settings";
 import { defaultLocale, locales, t, type Locale } from "@/config/i18n";
 import { buildGitHubRepoUrl } from "@/utils/github";
 import {
-  buildLocaleLinks,
   docsUrl,
   navHref,
   stripBase,
   versionedDocsUrl,
   withBase,
 } from "@/utils/base";
-import {
-  type NavNode,
-} from "@/utils/docs";
-import { buildSidebarForSection } from "@/utils/sidebar";
 import { filterHeaderRightItems } from "@takazudo/zudo-doc/header";
 import { SearchWidget } from "./_search-widget";
-import { loadNavSourceDocs } from "./_nav-source-docs";
-
-// ---------------------------------------------------------------------------
-// Internal helpers
-// ---------------------------------------------------------------------------
-
-/**
- * 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).
- *
- * Intentionally kept as a local copy in this module (not extracted) —
- * T2 only dedupes loadNavSourceDocs; remapVersionedHrefs is out of scope.
- */
-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 };
-  });
-}
+import {
+  buildRootMenuItems,
+  buildLocaleLinksForNav,
+  buildSidebarNodes,
+  getThemeDefaultMode,
+} from "./_nav-data-prep";
 
 // ---------------------------------------------------------------------------
 // Component
@@ -114,7 +76,7 @@ function remapVersionedHrefs(
 
 export interface HeaderWithDefaultsProps {
   /** Active locale; defaults to the configured defaultLocale. */
-  lang?: Locale;
+  lang?: Locale | string;
   /**
    * Current page URL path (as the layout passes from Astro.url.pathname or
    * the zfb equivalent). Used by the Header to compute the active nav item
@@ -151,27 +113,21 @@ export function HeaderWithDefaults(
   props: HeaderWithDefaultsProps,
 ): JSX.Element {
   const {
-    lang = defaultLocale,
+    lang: langProp = defaultLocale,
     currentPath = "",
     currentVersion,
     currentSlug,
     navSection,
   } = props;
+  // Route params arrive as `string`; cast to Locale since keys of settings.locales
+  // are always valid locale codes. The prop accepts `Locale | string` so callers
+  // without a Locale variable don't need to cast (e.g. _tag-pages.tsx).
+  const lang = langProp as Locale;
 
-  // Root-menu items for the mobile sidebar's "back to menu" list.
-  // Mirrors the data-prep in _sidebar-with-defaults.tsx.
-  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, locale links, sidebar nodes, 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);
 
   // Build the mobile sidebar toggle unconditionally — SidebarToggle is rendered
   // on every page (refs #1453); the host CSS hides it where unneeded. When navSection is
@@ -182,21 +138,11 @@ export function HeaderWithDefaults(
 
   // Locale-switcher links in the mobile sidebar footer — only when
   // multiple locales are configured (mirrors _sidebar-with-defaults.tsx).
-  const localeLinks =
-    locales.length > 1 ? buildLocaleLinks(currentPath, lang) : undefined;
+  const localeLinks = buildLocaleLinksForNav(currentPath, lang, locales.length);
 
-  const themeDefaultMode = settings.colorMode
-    ? settings.colorMode.defaultMode
-    : undefined;
+  const themeDefaultMode = getThemeDefaultMode();
 
-  let sidebarNodes: NavNode[] = [];
-  if (navSection !== undefined) {
-    const { navDocs, categoryMeta } = loadNavSourceDocs(lang, currentVersion);
-    const rawNodes = buildSidebarForSection(navDocs, lang, navSection, categoryMeta);
-    sidebarNodes = currentVersion
-      ? remapVersionedHrefs(rawNodes, currentVersion, lang)
-      : rawNodes;
-  }
+  const sidebarNodes = buildSidebarNodes(lang, navSection, currentVersion);
 
   // Wrap SidebarToggle (hamburger button + slide-in aside + SidebarTree) in
   // Island so the SSG output carries the full tree HTML AND the
@@ -211,8 +157,25 @@ export function HeaderWithDefaults(
   // nested as a JSX child its data was dropped during hydration and
   // SidebarToggle re-rendered with `children=undefined`, wiping the SSR
   // tree DOM. zudolab/zudo-doc#1355 wave 13.5.
+  //
+  // C4 — media-gated hydration.  zfb only supports load|idle|visible
+  // strategies (no "media" strategy; matchMedia inside the component is too
+  // late — props are already emitted, bundle already downloaded).
+  // Upstream feature request: Takazudo/zudo-front-builder#969.
+  //
+  // Best achievable downstream: when="visible" + all SidebarToggle children
+  // are lg:hidden, so on desktop the Island wrapper div has zero rendered
+  // dimensions.  IntersectionObserver fires isIntersecting=false on desktop
+  // (zero-size element) → Preact hydrate() is never called.  On mobile (and
+  // on desktop→mobile resize) the children become visible, the element gains
+  // size, IO fires isIntersecting=true, and hydration completes normally.
+  //
+  // Residual: data-props JSON (~2.4 KB) is still emitted in the SSR HTML on
+  // every page regardless of viewport, because it is serialised at build time
+  // and not gated by media. Eliminating it requires a zfb "media" hydration
+  // strategy — tracked in Takazudo/zudo-front-builder#969.
   const sidebarToggle = Island({
-    when: "load",
+    when: "visible",
     children: (
       <SidebarToggle
         nodes={sidebarNodes}
@@ -225,15 +188,12 @@ export function HeaderWithDefaults(
     ),
   }) as unknown as VNode;
 
-  // Wrap the host's local ThemeToggle in Island({when:"load"}) so the SSG
+  // Wrap the bare ThemeToggle in Island({when:"load"}) so the SSG
   // output emits a data-zfb-island="ThemeToggle" marker the hydration
-  // runtime can find — matching the documented header contract. The v2
-  // package's <ThemeToggle> already does this internally, but importing it
-  // forces the v2 theme barrel into the bundle (see import note at the top
-  // of this file).
+  // runtime can find — matching the documented header contract.
   const themeToggle = Island({
     when: "load",
-    children: <ThemeToggle />,
+    children: <ThemeToggle defaultMode={themeDefaultMode} />,
   }) as unknown as VNode;
 
   // Locale-aware search widget. Renders the full dialog markup in SSR
@@ -269,7 +229,9 @@ export function HeaderWithDefaults(
     );
     // "Latest" entry links to the current page in the latest (unversioned)
     // docs when a slug is available, or falls back to the versions index page.
-    const latestUrl = currentSlug
+    // Null check, not truthiness: "" is the canonical root-index slug (#1891)
+    // and must produce real per-version root URLs.
+    const latestUrl = currentSlug != null
       ? docsUrl(currentSlug, lang)
       : versionsPageUrl;
 
@@ -278,7 +240,7 @@ export function HeaderWithDefaults(
     // index — matching the documented version-switcher contract.
     const versionUrls: Record<string, string> = {};
     for (const v of settings.versions) {
-      versionUrls[v.slug] = currentSlug
+      versionUrls[v.slug] = currentSlug != null
         ? versionedDocsUrl(currentSlug, v.slug, lang)
         : versionsPageUrl;
     }

package/templates/base/pages/lib/_inline-version-switcher.tsx

@@ -51,13 +51,14 @@ export function buildInlineVersionSwitcher(
   const versionsPageUrl = withBase(
     isNonDefaultLocale ? `/${locale}/docs/versions` : "/docs/versions",
   );
-  const latestUrl = slug ? docsUrl(slug, locale) : versionsPageUrl;
+  // The docs root index has the canonical empty slug "" (#1891), and
+  // docsUrl("")/versionedDocsUrl("") resolve to the per-version docs roots —
+  // so an empty slug must NOT fall back to the versions page.
+  const latestUrl = docsUrl(slug, locale);
 
   const versionUrls: Record<string, string> = {};
   for (const v of settings.versions) {
-    versionUrls[v.slug] = slug
-      ? versionedDocsUrl(slug, v.slug, locale)
-      : versionsPageUrl;
+    versionUrls[v.slug] = versionedDocsUrl(slug, v.slug, locale);
   }
 
   const labels: VersionSwitcherLabels = {

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