create-zudo-doc 0.2.0 → 0.2.2

package/templates/base/pages/lib/_doc-route-entries.ts

@@ -0,0 +1,188 @@
+// Shared, memoized route-entry builder for the 4 doc catch-all routes.
+//
+// Extracted (#2010) from the ~85%-duplicated paths() bodies of:
+//   pages/docs/[[...slug]].tsx
+//   pages/[locale]/docs/[[...slug]].tsx
+//   pages/v/[version]/docs/[[...slug]].tsx
+//   pages/v/[version]/[locale]/docs/[[...slug]].tsx
+//
+// Each route resolves its own identity-stable nav source (resolveNavSource /
+// resolveVersionedLocaleSource) and URL closure, then delegates the per-entry
+// derived-data work here. The result is memoized with the #1902 WeakMap
+// pattern (memoizeDerived keyed on the identity-stable `source.docs` array +
+// a per-route signature), so the expensive per-entry work — extractHeadings,
+// buildBreadcrumbs, prev/next resolution — runs ONCE per entry per build,
+// not once per entry per page (zfb re-invokes paths() once per built page).
+//
+// Versioned-vs-latest behavior is keyed on the presence of `urlFor` (#1916):
+//   - `urlFor` set (versioned routes): breadcrumbs resolve against the NAV
+//     tree (unlisted excluded) with crumbs remapped to the versioned URL
+//     space; prev/next hrefs are rewritten through the closure; auto-index
+//     child-card hrefs are ALWAYS remapped to the versioned URL.
+//   - `urlFor` unset (latest routes): breadcrumbs resolve against the FULL
+//     tree (unlisted included, for accurate crumbs); prev/next and child
+//     hrefs keep the latest `docsUrl` already baked into the nav nodes.
+// These two behaviors travel together by construction: only versioned routes
+// own a versioned URL closure (see _doc-route-paths.ts for the #1916
+// rationale on why latest routes must never receive one).
+
+import {
+  buildNavTree,
+  buildBreadcrumbs,
+  collectAutoIndexNodes,
+  type NavNode,
+} from "@/utils/docs";
+import { getNavSectionForSlug, getNavSubtree } from "@/utils/nav-scope";
+import { toRouteSlug, toSlugParams } from "@/utils/slug";
+import type { Locale } from "@/config/i18n";
+import { extractHeadings } from "./_extract-headings";
+import type { AutoIndexNode, DocPageBaseProps } from "./doc-page-props";
+import { memoizeDerived } from "./_nav-source-cache";
+import type { NavSourceDocs } from "./_nav-source-docs";
+import {
+  resolveDocPrevNext,
+  flattenSubtree,
+  rewriteNavHref,
+  remapNavChildHrefs,
+} from "./_doc-route-paths";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** One enumerated doc route: a content entry or an auto-generated category
+ *  index, with all per-page derived data pre-computed. */
+export interface DocRouteEntry {
+  /** Canonical route slug ("" for the docs root index — #1891). */
+  slug: string;
+  /** Optional-catchall params array — `toSlugParams(slug)` ([] for the root). */
+  slugParams: string[];
+  /**
+   * True when the entry came from the base collection rather than the locale
+   * collection (`!localeSlugSet.has(slug)`). Only meaningful on routes whose
+   * nav source performs a locale merge — routes without one (default-locale /
+   * versioned-EN, where `localeSlugSet` is empty) must ignore this field.
+   * Always false for autoIndex items.
+   */
+  isFallback: boolean;
+  /** Shared page props (kind/entry/autoIndex/breadcrumbs/prev/next/headings). */
+  props: DocPageBaseProps;
+}
+
+export interface BuildDocRouteEntriesArgs {
+  /** Identity-stable nav source for this route's (locale, version) context —
+   *  from resolveNavSource / resolveVersionedLocaleSource. The memo is keyed
+   *  on `source.docs` identity, so the source MUST come from those resolvers
+   *  (a fresh array defeats the memo — harmless, but recomputes per call). */
+  source: NavSourceDocs;
+  /** Active locale for nav-tree labels and breadcrumbs. */
+  locale: Locale;
+  /**
+   * Unique memo signature for this route context. Each route file passes its
+   * own prefix plus the loop variables (version slug / locale), e.g.
+   * "docs;en", "locale-docs;ja", "v-docs;1.0", "v-locale-docs;1.0;ja" —
+   * call sites that share a docs array identity must never collide on a key.
+   */
+  routeSig: string;
+  /** Versioned URL closure bound to the route's version (+ locale). Presence
+   *  switches the versioned behaviors documented in the module header. */
+  urlFor?: (slug: string) => string;
+}
+
+// ---------------------------------------------------------------------------
+// buildDocRouteEntries
+// ---------------------------------------------------------------------------
+
+/**
+ * Enumerate all doc routes (content entries + auto-index pages) for one
+ * (locale, version) context, with per-entry derived data pre-computed.
+ *
+ * Memoized per build on the identity-stable `source.docs` array (#1902), so
+ * repeated paths() invocations across the route's many pages return the SAME
+ * array instance without redoing the per-entry work. In the no-snapshot
+ * fallback path (unit tests / direct Node runs) `source.docs` is a fresh
+ * array per call, so the memo misses and this computes fresh — matching the
+ * deliberate no-memo policy in _nav-source-cache.ts.
+ */
+export function buildDocRouteEntries(
+  args: BuildDocRouteEntriesArgs,
+): DocRouteEntry[] {
+  const { source, locale, routeSig, urlFor } = args;
+
+  return memoizeDerived([source.docs], `docRouteEntries;${routeSig}`, () => {
+    const { docs, navDocs, categoryMeta, localeSlugSet } = source;
+
+    // Nav docs: exclude unlisted (for sidebar/prev-next) but keep for breadcrumbs
+    const tree = buildNavTree(navDocs, locale, categoryMeta);
+    // Breadcrumb tree: latest routes use the full tree (including unlisted)
+    // for accurate crumbs; versioned routes resolve crumbs against the nav
+    // tree itself (#1916 #1).
+    const breadcrumbTree = urlFor ? tree : buildNavTree(docs, locale, categoryMeta);
+
+    const result: DocRouteEntry[] = [];
+
+    // Regular doc pages
+    for (const entry of docs) {
+      // A `category_no_page` index.mdx carries category metadata only — keep
+      // it in the nav tree (built above, used for breadcrumbs) but emit NO
+      // route for it. zfb's walker retains every .mdx as a collection entry,
+      // so without this explicit skip the metadata file would silently add a
+      // route.
+      if (entry.data.category_no_page === true) continue;
+      // Canonical route slug via the one shared rule (@/utils/slug) — yields
+      // "" for a root index (URL /docs/ — #1891).
+      const slug = entry.data.slug ?? toRouteSlug(entry.slug);
+      const navSection = getNavSectionForSlug(slug);
+      const subtree = getNavSubtree(tree, navSection);
+
+      // Prev/next + frontmatter pagination overrides resolved against THIS
+      // route's own `tree`; versioned routes then rewrite the hrefs through
+      // their urlFor closure (latest routes pass it through unchanged).
+      const { prev: prevNode, next: nextNode } = resolveDocPrevNext(
+        tree,
+        flattenSubtree(subtree),
+        slug,
+        entry.data,
+      );
+
+      result.push({
+        slug,
+        slugParams: toSlugParams(slug),
+        isFallback: !localeSlugSet.has(slug),
+        props: {
+          kind: "entry",
+          entry,
+          breadcrumbs: buildBreadcrumbs(breadcrumbTree, slug, locale, urlFor),
+          prev: rewriteNavHref(prevNode, urlFor),
+          next: rewriteNavHref(nextNode, urlFor),
+          headings: extractHeadings(entry.body ?? ""),
+        },
+      });
+    }
+
+    // Auto-generated index pages for categories without index.mdx
+    for (const node of collectAutoIndexNodes(tree)) {
+      result.push({
+        slug: node.slug,
+        slugParams: toSlugParams(node.slug),
+        isFallback: false,
+        props: {
+          kind: "autoIndex",
+          autoIndex: urlFor
+            ? // #1916 #2: child-card hrefs ALWAYS resolve to the versioned URL.
+              ({
+                ...node,
+                children: remapNavChildHrefs(node.children, urlFor) as NavNode[],
+              } as AutoIndexNode)
+            : (node as AutoIndexNode),
+          breadcrumbs: buildBreadcrumbs(breadcrumbTree, node.slug, locale, urlFor),
+          prev: null,
+          next: null,
+          headings: [],
+        },
+      });
+    }
+
+    return result;
+  });
+}

package/templates/base/pages/lib/_doc-tags-area.tsx

@@ -34,12 +34,17 @@ import { DocTags } from "@takazudo/zudo-doc/metainfo";
  *
  * Inlined from _footer-with-defaults.tsx `tagHref` — not extracted to avoid
  * ripple (spec rule: no opportunistic refactor on tagHref extraction).
+ *
+ * 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, locale: string): string {
+  const encoded = encodeURIComponent(tag);
   const path =
     locale === defaultLocale
-      ? `/docs/tags/${tag}`
-      : `/${locale}/docs/tags/${tag}`;
+      ? `/docs/tags/${encoded}`
+      : `/${locale}/docs/tags/${encoded}`;
   return withBase(path);
 }
 

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,33 @@ 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";
+// 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";
 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 +79,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 +116,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 +141,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 +160,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 +191,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 +232,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 +243,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 = {