@takazudo/zudo-doc 5.5.2 → 5.6.0

package/dist/doc-route-entries/index.d.ts

@@ -2,100 +2,15 @@ import type { DocPageEntry, DocNavNode, AutoIndexNode, DocPageBaseProps } from "
 import type { NavSourceDocs } from "../nav-source-docs/index.js";
 import type { BreadcrumbItem } from "../breadcrumb/types.js";
 import type { HeadingItem } from "../extract-headings/index.js";
-import type { CategoryMeta } from "../sidebar-tree/index.js";
+import type { BuildDocRouteEntriesArgs as BuildDocRouteEntriesArgsGeneric, DocRouteEntriesAPI as DocRouteEntriesAPIGeneric, DocRouteEntriesContext as DocRouteEntriesContextGeneric, DocRouteEntry as DocRouteEntryGeneric } from "../site-schema/doc-route-entries.js";
+export { createDocRouteEntries } from "../site-schema/doc-route-entries.js";
 export type { DocPageEntry, DocNavNode, AutoIndexNode, DocPageBaseProps, NavSourceDocs };
-/** 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. */
-    source: NavSourceDocs;
-    /** Active locale for nav-tree labels and breadcrumbs. */
-    locale: string;
-    /**
-     * 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 (breadcrumbs, prev/next, child hrefs). */
-    urlFor?: (slug: string) => string;
-}
 export type { BreadcrumbItem, HeadingItem };
-/**
- * Context slice `createDocRouteEntries` derives its bag from (epic Collapse
- * Wiring Shells #2420, FACTORIES #2424 — breaking signature). STRUCTURAL SUBSET
- * of the unified `RouteContext`/`ChromeContext` — the nav-tree builder is
- * reconstructed by binding the context's 4-arg `buildNavTree` to `docsUrl`, and
- * the breadcrumb trail by binding the package `buildBreadcrumbs` to the
- * locale-prefixed `withBase` base, exactly as the pre-collapse wiring did.
- */
-export interface DocRouteEntriesContext {
-    /** Default locale code (drives the breadcrumb base-prefix selection). */
-    defaultLocale: string;
-    /** Build the nav tree for a locale (4-arg form with an explicit href builder). */
-    buildNavTree: (docs: DocPageEntry[], locale: string, categoryMeta: Map<string, CategoryMeta> | undefined, buildHref: (slug: string, locale: string) => string) => DocNavNode[];
-    /** Build a docs URL for the given slug and locale. */
-    docsUrl: (slug: string, locale?: string) => string;
-    /** Prefix a path with the configured base directory. */
-    withBase: (path: string) => string;
-    /** Collect all auto-generated index nodes (categories without index.mdx). */
-    collectAutoIndexNodes: (tree: DocNavNode[]) => AutoIndexNode[];
-    /** Determine the nav section (categoryMatch) for a slug. */
-    getNavSectionForSlug: (slug: string) => string | undefined;
-    /** Filter top-level nav nodes by a categoryMatch value. */
-    getNavSubtree: (tree: DocNavNode[], categoryMatch?: string) => DocNavNode[];
-    /** Convert a content entry slug to a canonical route slug. */
-    toRouteSlug: (entrySlug: string) => string;
-    /** Convert a canonical route slug to an optional-catchall params array. */
-    toSlugParams: (slug: string) => string[];
-    /** Extract headings from a raw MDX body (bound to settings depth/strategy). */
-    extractHeadings: (body: string) => HeadingItem[];
-}
-/**
- * Result of `createDocRouteEntries`. Contains the `buildDocRouteEntries`
- * function bound to the injected context.
- */
-export interface DocRouteEntriesAPI {
-    /**
-     * Enumerate all doc routes for one (locale, version) context, with per-entry
-     * derived data pre-computed. Memoized per build on the identity-stable
-     * `source.docs` array.
-     */
-    buildDocRouteEntries: (args: BuildDocRouteEntriesArgs) => DocRouteEntry[];
-}
-/**
- * Create the `buildDocRouteEntries` function bound to the host's injected
- * context.
- *
- * @example
- * ```ts
- * // pages/lib/_doc-route-entries.ts (thin stub)
- * import { createDocRouteEntries } from "@takazudo/zudo-doc/doc-route-entries";
- * import { buildNavTree, buildBreadcrumbs, collectAutoIndexNodes } from "@/utils/docs";
- * import { getNavSectionForSlug, getNavSubtree } from "@/utils/nav-scope";
- * import { toRouteSlug, toSlugParams } from "@takazudo/zudo-doc/slug";
- * import { extractHeadings } from "./_extract-headings";
- *
- * export const { buildDocRouteEntries } = createDocRouteEntries(routeContext);
- * export type { DocRouteEntry, BuildDocRouteEntriesArgs };
- * ```
- */
-export declare function createDocRouteEntries(ctx: DocRouteEntriesContext): DocRouteEntriesAPI;
+/** One enumerated doc route, carrying a zfb collection entry. */
+export type DocRouteEntry = DocRouteEntryGeneric<DocPageEntry>;
+/** Arguments to `buildDocRouteEntries` for one (locale, version) context. */
+export type BuildDocRouteEntriesArgs = BuildDocRouteEntriesArgsGeneric<DocPageEntry>;
+/** The context slice `createDocRouteEntries` derives its bag from. */
+export type DocRouteEntriesContext = DocRouteEntriesContextGeneric<DocPageEntry>;
+/** The functions `createDocRouteEntries` returns. */
+export type DocRouteEntriesAPI = DocRouteEntriesAPIGeneric<DocPageEntry>;

package/dist/doc-route-entries/index.js

@@ -1,81 +1,4 @@
-import { memoizeDerived } from "../nav-source-cache/index.js";
-import { buildBreadcrumbs as buildBreadcrumbsImpl } from "../routes/_docs-helpers.js";
-import {
-  resolveDocPrevNext,
-  flattenSubtree,
-  rewriteNavHref,
-  remapNavChildHrefs
-} from "../doc-route-paths/index.js";
-function createDocRouteEntries(ctx) {
-  const defaultLocale = ctx.defaultLocale;
-  const buildNavTree = (docs, locale, categoryMeta) => ctx.buildNavTree(docs, locale, categoryMeta, (slug, loc) => ctx.docsUrl(slug, loc));
-  const buildBreadcrumbs = (tree, slug, locale, urlFor) => buildBreadcrumbsImpl(
-    tree,
-    slug,
-    locale === defaultLocale ? ctx.withBase("/") : ctx.withBase(`/${locale}/`),
-    urlFor
-  );
-  const collectAutoIndexNodes = ctx.collectAutoIndexNodes;
-  const getNavSectionForSlug = ctx.getNavSectionForSlug;
-  const getNavSubtree = ctx.getNavSubtree;
-  const toRouteSlug = ctx.toRouteSlug;
-  const toSlugParams = ctx.toSlugParams;
-  const extractHeadings = ctx.extractHeadings;
-  function buildDocRouteEntries(args) {
-    const { source, locale, routeSig, urlFor } = args;
-    return memoizeDerived([source.docs], `docRouteEntries;${routeSig}`, () => {
-      const { docs, navDocs, categoryMeta, localeSlugSet } = source;
-      const tree = buildNavTree(navDocs, locale, categoryMeta);
-      const breadcrumbTree = urlFor ? tree : buildNavTree(docs, locale, categoryMeta);
-      const result = [];
-      for (const entry of docs) {
-        if (entry.data.category_no_page === true) continue;
-        const slug = entry.data.slug ?? toRouteSlug(entry.slug);
-        const navSection = getNavSectionForSlug(slug);
-        const subtree = getNavSubtree(tree, navSection);
-        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 ?? "")
-          }
-        });
-      }
-      for (const node of collectAutoIndexNodes(tree)) {
-        result.push({
-          slug: node.slug,
-          slugParams: toSlugParams(node.slug),
-          isFallback: false,
-          props: {
-            kind: "autoIndex",
-            autoIndex: urlFor ? {
-              ...node,
-              children: remapNavChildHrefs(node.children, urlFor)
-            } : node,
-            breadcrumbs: buildBreadcrumbs(breadcrumbTree, node.slug, locale, urlFor),
-            prev: null,
-            next: null,
-            headings: []
-          }
-        });
-      }
-      return result;
-    });
-  }
-  return { buildDocRouteEntries };
-}
+import { createDocRouteEntries } from "../site-schema/doc-route-entries.js";
 export {
   createDocRouteEntries
 };

package/dist/doc-route-paths/index.d.ts

@@ -1,4 +1,4 @@
-import type { DocNavNode } from "../doc-page-props/index.js";
+import type { DocNavNode } from "../site-schema/types.js";
 export type { DocNavNode };
 /**
  * Flatten a nav tree into a pre-order traversal array.

package/dist/head-with-defaults/index.d.ts

@@ -4,7 +4,7 @@ import type { JSX } from "preact";
 import type { HeadProps } from "../head/types.js";
 import type { ColorSchemeProviderColorMode } from "../theme/color-scheme-provider.js";
 import type { ChromeContext } from "../factory-context/index.js";
-import type { Settings } from "../settings.js";
+import type { Settings, FaviconConfig } from "../settings.js";
 export interface HeadWithDefaultsProps {
     /** Page title forwarded to og:title. Required. */
     title: string;
@@ -33,6 +33,8 @@ export interface HeadWithDefaultsSettings {
     sidebarResizer?: boolean;
     /** Configured theme-pack slug (ADR `docs/adr/theme-packs.md`, #2822). */
     themePack?: string;
+    /** Favicon link set — see {@link resolveFaviconLinks} for the emission table. */
+    favicon?: string | FaviconConfig | false;
 }
 /**
  * Create a `HeadWithDefaults` component from the unified {@link ChromeContext}

package/dist/head-with-defaults/index.js

@@ -6,8 +6,82 @@ import ThemePackProvider, {
   themePackVersionMap
 } from "../theme/theme-pack-provider.js";
 import { DEFAULT_THEME_PACK_SLUG } from "../theme-pack-switcher/theme-pack-sync.js";
+import { renderAutoLogoIconSvg } from "../auto-logo/icon.js";
 import { deriveComposeMetaTitle, deriveColorSchemeGenerators } from "../chrome/derive.js";
 import { assertChromeContext } from "../chrome/assert-chrome-context.js";
+const FAVICON_AUTO = "auto";
+const DEFAULT_FAVICON = {
+  svg: "/favicon.svg",
+  ico: "/favicon.ico",
+  png32: "/favicon-32x32.png",
+  png16: "/favicon-16x16.png"
+};
+const FAVICON_TYPE_BY_EXT = {
+  svg: "image/svg+xml",
+  png: "image/png",
+  ico: "image/x-icon",
+  jpg: "image/jpeg",
+  jpeg: "image/jpeg",
+  gif: "image/gif",
+  webp: "image/webp",
+  avif: "image/avif"
+};
+function faviconType(value) {
+  const path = value.split(/[?#]/)[0] ?? "";
+  const file = path.slice(path.lastIndexOf("/") + 1);
+  const dot = file.lastIndexOf(".");
+  if (dot < 0) return void 0;
+  return FAVICON_TYPE_BY_EXT[file.slice(dot + 1).toLowerCase()];
+}
+function faviconHref(value, withBase) {
+  return value.startsWith("/") ? withBase(value) : value;
+}
+function resolveFaviconLinks(favicon, siteName, withBase) {
+  if (favicon === false) return [];
+  if (typeof favicon === "string") {
+    if (favicon === FAVICON_AUTO) {
+      const svg = encodeURIComponent(renderAutoLogoIconSvg(siteName));
+      return [{ rel: "icon", type: "image/svg+xml", href: `data:image/svg+xml,${svg}` }];
+    }
+    const type = faviconType(favicon);
+    return [
+      {
+        rel: "icon",
+        ...type !== void 0 ? { type } : {},
+        href: faviconHref(favicon, withBase)
+      }
+    ];
+  }
+  const slots = favicon ?? DEFAULT_FAVICON;
+  const links = [];
+  if (slots.svg !== void 0) {
+    links.push({
+      rel: "icon",
+      type: faviconType(slots.svg) ?? "image/svg+xml",
+      href: faviconHref(slots.svg, withBase)
+    });
+  }
+  if (slots.ico !== void 0) {
+    links.push({ rel: "icon", href: faviconHref(slots.ico, withBase), sizes: "any" });
+  }
+  if (slots.png32 !== void 0) {
+    links.push({
+      rel: "icon",
+      type: faviconType(slots.png32) ?? "image/png",
+      sizes: "32x32",
+      href: faviconHref(slots.png32, withBase)
+    });
+  }
+  if (slots.png16 !== void 0) {
+    links.push({
+      rel: "icon",
+      type: faviconType(slots.png16) ?? "image/png",
+      sizes: "16x16",
+      href: faviconHref(slots.png16, withBase)
+    });
+  }
+  return links;
+}
 function createHeadWithDefaults(ctx) {
   assertChromeContext(ctx, "createHeadWithDefaults");
   const settings = ctx.settings;
@@ -19,6 +93,7 @@ function createHeadWithDefaults(ctx) {
   const themePackEnabled = themePackRegistry !== null ? themePackVersionMap(themePackRegistry) : null;
   const themePackConfigured = settings.themePack ?? DEFAULT_THEME_PACK_SLUG;
   const themePackBase = withBase("/");
+  const faviconLinks = resolveFaviconLinks(settings.favicon, settings.siteName, withBase);
   function HeadWithDefaults({
     title,
     description,
@@ -65,10 +140,7 @@ function createHeadWithDefaults(ctx) {
         }
       ),
       settings.sidebarResizer && /* @__PURE__ */ jsx("script", { dangerouslySetInnerHTML: { __html: SIDEBAR_RESIZER_RESTORE_SCRIPT } }),
-      /* @__PURE__ */ jsx("link", { rel: "icon", type: "image/svg+xml", href: withBase("/favicon.svg") }),
-      /* @__PURE__ */ jsx("link", { rel: "icon", href: withBase("/favicon.ico"), sizes: "any" }),
-      /* @__PURE__ */ jsx("link", { rel: "icon", type: "image/png", sizes: "32x32", href: withBase("/favicon-32x32.png") }),
-      /* @__PURE__ */ jsx("link", { rel: "icon", type: "image/png", sizes: "16x16", href: withBase("/favicon-16x16.png") }),
+      faviconLinks.map((attrs, i) => /* @__PURE__ */ jsx("link", { ...attrs }, i)),
       canonical !== void 0 && /* @__PURE__ */ jsx("link", { rel: "canonical", href: canonical }),
       ctx.settings.head && /* @__PURE__ */ jsxs(Fragment, { children: [
         ctx.settings.head.preconnect?.map((p, i) => /* @__PURE__ */ jsx(

package/dist/header/nav-active.d.ts

@@ -25,6 +25,34 @@ export interface NavItemLike {
  *   pathForMatch(null,            "ja", "en") === ""
  */
 export declare function pathForMatch(pathWithoutBase: string, lang: string | undefined, defaultLocale: string): string;
+/**
+ * Pick the deepest header-nav path that the current page lives under.
+ *
+ * The legacy template flattens parent + child paths, filters by
+ * `pathForMatch.startsWith(p)`, and picks the longest match — this keeps
+ * a child link active even when its parent's path is also a prefix of
+ * the current page.
+ *
+ * Returns `undefined` when no nav entry matches; callers should treat
+ * that as "no active link."
+ */
+/**
+ * Segment-aware prefix test: nav path `/docs/guides` matches `/docs/guides`
+ * and `/docs/guides/...` but NOT `/docs/guideship`.
+ *
+ * Exported (not just module-private) so `nav-overflow-script.ts` can embed it
+ * verbatim via `.toString()` alongside `computeActiveNavPath` — that function
+ * closes over this one, so a bare `computeActiveNavPath.toString()` embed
+ * would reference an undefined `pathMatchesNavPath` in the browser (see the
+ * caution note on `computeActiveNavPath` below). Kept self-contained (no
+ * outer references) for the same reason.
+ */
+export declare function pathMatchesNavPath(currentPath: string, navPath: string): boolean;
+/**
+ * CAUTION (zudolab/zudo-doc#3398): this closes over `pathMatchesNavPath`
+ * above. `nav-overflow-script.ts` embeds both via `.toString()` (never this
+ * one alone) so the generated browser script is self-contained.
+ */
 export declare function computeActiveNavPath(navItems: readonly NavItemLike[], pathForMatchValue: string): string | undefined;
 /**
  * Active-state predicate for a top-level nav item: the item itself, or

package/dist/header/nav-active.js

@@ -34,5 +34,6 @@ export {
   computeActiveNavPath,
   isNavItemActive,
   isNavItemActiveByCategory,
-  pathForMatch
+  pathForMatch,
+  pathMatchesNavPath
 };

package/dist/header/nav-overflow-script.js

@@ -1,4 +1,6 @@
 import { AFTER_NAVIGATE_EVENT } from "../transitions/page-events.js";
+import { CURRENT_PATH_SCRIPT_PRELUDE } from "../current-path/index.js";
+import { computeActiveNavPath, pathMatchesNavPath } from "./nav-active.js";
 import {
   NAV_CHEVRON_ACTIVE,
   NAV_CHEVRON_INACTIVE,
@@ -29,20 +31,26 @@ const NAV_OVERFLOW_SCRIPT = `(function () {
     catch (e) { return ""; }
   }
 
-  function isUnderPath(cur, p) {
-    if (!p) return false;
-    if (cur === p) return true;
-    return p !== "/" && cur.indexOf(p + "/") === 0;
-  }
+  // Explicit current-route override, embedded from current-path/index.ts so
+  // this script cannot drift from the three other read sites
+  // (zudolab/zudo-doc#3398, #3408).
+  ${CURRENT_PATH_SCRIPT_PRELUDE}
+
+  // Shared matching core (zudolab/zudo-doc#3398): embedded verbatim from
+  // nav-active.ts so this script's longest-match walk cannot drift from the
+  // SSR header's own computeActiveNavPath call (header.tsx). computeActiveNavPath
+  // closes over pathMatchesNavPath, so both are embedded together.
+  var pathMatchesNavPath = ${pathMatchesNavPath.toString()};
+  var computeActiveNavPath = ${computeActiveNavPath.toString()};
 
   // Recompute which header nav item is "active" from the CURRENT URL and
   // repaint the highlight. SSR sets the active item on first paint, but the
   // header is persisted across same-locale client-router swaps
   // (data-zfb-transition-persist), so without this the highlight would stay
   // frozen on the page where the header was first rendered. Mirrors the
-  // sidebar island's client-side approach (match location.pathname against
+  // sidebar island's client-side approach (match the current path against
   // each entry's href) and the SSR longest-match + dropdown-parent rules.
-  // URL-based: hrefs and location.pathname both carry the base + locale
+  // URL-based: hrefs and the current path both carry the base + locale
   // prefix, so they compare directly without stripping.
   function applyActiveNav() {
     var nav = document.querySelector("[data-header-nav]");
@@ -50,26 +58,31 @@ const NAV_OVERFLOW_SCRIPT = `(function () {
     var topItems = Array.from(nav.querySelectorAll(":scope > [data-nav-item]"));
     if (topItems.length === 0) return;
 
-    var cur = trimSlashes(location.pathname);
+    var cur = trimSlashes(readCurrentPath(CURRENT_PATH_DATASET_KEY));
 
-    // Deepest (longest) nav path the current URL lives under, across both
-    // top-level and dropdown-child paths \u2014 matches computeActiveNavPath.
-    var activePath = "";
+    // Build NavItemLike-shaped entries from the live DOM so the shared
+    // computeActiveNavPath can do the deepest-match walk \u2014 the same call
+    // shape the SSR header uses (matches computeActiveNavPath). A dropdown
+    // missing its own top-level anchor is skipped entirely (path "" would
+    // otherwise match every current path \u2014 pathMatchesNavPath treats "" as
+    // the root "/"), mirroring the parentLink guard used below for the same
+    // malformed-markup case.
+    var navItems = [];
     topItems.forEach(function (it) {
       var isDropdown = it.hasAttribute("data-nav-item-dropdown");
       var topA = isDropdown ? it.querySelector(":scope > a") : it;
-      if (topA) {
-        var tp = navPathname(topA);
-        if (isUnderPath(cur, tp) && tp.length > activePath.length) activePath = tp;
-      }
+      if (!topA) return;
+      var children = [];
       if (isDropdown) {
         it.querySelectorAll(":scope > div a").forEach(function (c) {
-          var cp = navPathname(c);
-          if (isUnderPath(cur, cp) && cp.length > activePath.length) activePath = cp;
+          children.push({ path: navPathname(c) });
         });
       }
+      navItems.push({ path: navPathname(topA), children: children });
     });
 
+    var activePath = computeActiveNavPath(navItems, cur) || "";
+
     function setTopActive(a, active) {
       if (!a) return;
       if (active) {

package/dist/header-with-defaults/index.js

@@ -12,7 +12,8 @@ import { assertChromeContext } from "../chrome/assert-chrome-context.js";
 import {
   deriveGetUnavailableVersions,
   deriveNavDataPrep,
-  deriveSearchWidgetSlot
+  deriveSearchWidgetSlot,
+  skipsPackageDefaultDesignTokenPanel
 } from "../chrome/derive.js";
 function createHeaderWithDefaults(ctx) {
   assertChromeContext(ctx, "createHeaderWithDefaults");
@@ -130,7 +131,15 @@ function createHeaderWithDefaults(ctx) {
     const headerRightItems = filterHeaderRightItems(
       settings.headerRightItems ?? [],
       {
-        designTokenPanel: Boolean(settings.designTokenPanel),
+        // Mirrors `deriveBodyEndIslands`' slot resolution (#3414): when the
+        // derive-level skip leaves a page with no panel island and no
+        // pre-hydration toggle shim, the header toggle button must go with
+        // them — otherwise it dispatches `toggle-design-token-panel` into a
+        // document with no listener and no click queue (a dead button).
+        // `hostBindings.DesignTokenPanelBootstrap` covers the injected-route
+        // path too (`routes/_chrome.tsx` threads the configured island through
+        // that slot), so injected pages keep the button.
+        designTokenPanel: Boolean(settings.designTokenPanel) && (ctx.hostBindings.DesignTokenPanelBootstrap != null || !skipsPackageDefaultDesignTokenPanel(ctx.settings)),
         aiAssistant: Boolean(settings.aiAssistant),
         colorMode: Boolean(settings.colorMode),
         hasLocales: Object.keys(settings.locales).length > 0,

package/dist/i18n-version/language-switcher.d.ts

@@ -40,6 +40,12 @@ export declare function switchLocaleHref(pathname: string, config: LanguageSwitc
  * `window[FLAG]` makes it idempotent: the tag may re-execute on a hard reload
  * or a cross-locale header repaint, but the listener is registered exactly
  * once per page lifetime.
+ *
+ * The pathname fed to `switchLocaleHref` comes from the embedded
+ * `readCurrentPath`, which prefers the `data-zd-current-path` override over
+ * `location.pathname` — the same explicit current-route reader
+ * `nav-overflow-script.ts` / `sidebar-tree-island` / `version-switcher.tsx`
+ * use (zudolab/zudo-doc#3398, consolidated by #3408).
  */
 export declare const LANGUAGE_SWITCHER_INIT_SCRIPT: string;
 export interface LanguageSwitcherProps {

package/dist/i18n-version/language-switcher.js

@@ -1,6 +1,7 @@
 import { jsx, jsxs } from "preact/jsx-runtime";
 import { Fragment } from "preact";
 import { AFTER_NAVIGATE_EVENT } from "../transitions/index.js";
+import { CURRENT_PATH_SCRIPT_PRELUDE } from "../current-path/index.js";
 function switchLocaleHref(pathname, config, currentLang, targetLang) {
   const normalizedBase = config.base;
   const defaultLocale = config.defaultLocale;
@@ -45,6 +46,7 @@ const LANGUAGE_SWITCHER_INIT_SCRIPT = `(function(){
 var FLAG="__zdLanguageSwitcherInit";
 if(window[FLAG])return;
 window[FLAG]=true;
+${CURRENT_PATH_SCRIPT_PRELUDE}
 var switchLocaleHref=${switchLocaleHref.toString()};
 function rewire(){
 var containers=document.querySelectorAll("[data-language-switcher]");
@@ -57,7 +59,7 @@ for(var j=0;j<anchors.length;j++){
 var a=anchors[j];
 var target=a.getAttribute("lang");
 if(!target)continue;
-a.setAttribute("href",switchLocaleHref(window.location.pathname,config,currentLang,target));
+a.setAttribute("href",switchLocaleHref(readCurrentPath(CURRENT_PATH_DATASET_KEY),config,currentLang,target));
 }
 }
 }

package/dist/i18n-version/version-switcher.d.ts

@@ -208,6 +208,12 @@ export declare const VERSION_SWITCHER_INIT_SCRIPT: string;
  * `window[FLAG]` makes it idempotent: the tag may re-execute on a hard reload or
  * a cross-locale header repaint, but the listener registers exactly once per
  * page lifetime.
+ *
+ * The pathname fed to `computeVersionSwitcherState` comes from the embedded
+ * `readCurrentPath`, which prefers the `data-zd-current-path` override over
+ * `location.pathname` — the same explicit current-route reader
+ * `nav-overflow-script.ts` / `sidebar-tree-island` / `language-switcher.tsx`
+ * use (zudolab/zudo-doc#3398, consolidated by #3408).
  */
 export declare const VERSION_SWITCHER_REWIRE_SCRIPT: string;
 export type { VersionEntry, VersionSwitcherLabels };

package/dist/i18n-version/version-switcher.js

@@ -1,5 +1,6 @@
 import { jsx, jsxs } from "preact/jsx-runtime";
 import { AFTER_NAVIGATE_EVENT } from "../transitions/page-events.js";
+import { CURRENT_PATH_SCRIPT_PRELUDE } from "../current-path/index.js";
 import { UNAVAILABLE_VERSIONS_ATTR } from "../version-availability/index.js";
 function computeVersionSwitcherState(pathname, config, versionSlugs) {
   const normalizedBase = config.base;
@@ -235,6 +236,7 @@ var FLAG="__zdVersionSwitcherRewire";
 if(window[FLAG])return;
 window[FLAG]=true;
 var ATTR=${JSON.stringify(UNAVAILABLE_VERSIONS_ATTR)};
+${CURRENT_PATH_SCRIPT_PRELUDE}
 var computeVersionSwitcherState=${computeVersionSwitcherState.toString()};
 function setActive(a,active){
 a.classList.toggle("font-bold",active);
@@ -276,7 +278,7 @@ for(var j=0;j<versionAnchors.length;j++){
 var s=versionAnchors[j].getAttribute("data-version-slug");
 if(s)slugs.push(s);
 }
-var state=computeVersionSwitcherState(window.location.pathname,config,slugs);
+var state=computeVersionSwitcherState(readCurrentPath(CURRENT_PATH_DATASET_KEY),config,slugs);
 var latest=c.querySelector("[data-version-latest]");
 if(latest){
 latest.setAttribute("href",state.latestHref);

package/dist/nav-source-docs/index.d.ts

@@ -1,18 +1,14 @@
 import type { CategoryMeta } from "../sidebar-tree/index.js";
 import type { DocPageEntry } from "../doc-page-props/index.js";
+import type { NavSourceDocs as NavSourceDocsShape } from "../site-schema/types.js";
 import type { Settings } from "../settings.js";
 export type { CategoryMeta, DocPageEntry };
-export interface NavSourceDocs {
-    /** Full doc list (merged + draft-filtered; unlisted retained per options). */
-    docs: DocPageEntry[];
-    /** `docs.filter(isNavVisible)` — stable instance for buildNavTree. */
-    navDocs: DocPageEntry[];
-    /** Stable category-meta Map for the active (locale, version). */
-    categoryMeta: Map<string, CategoryMeta>;
-    /** Slugs that came from the locale collection (for isFallback). Empty for
-     *  default-locale / single-collection cases. */
-    localeSlugSet: ReadonlySet<string>;
-}
+/**
+ * The resolved nav source for one (locale, version) context, carrying zfb
+ * collection entries. The shape itself is browser-safe and declared in
+ * `../site-schema/types.js` (#3395); this alias pins it to `DocPageEntry`.
+ */
+export type NavSourceDocs = NavSourceDocsShape<DocPageEntry>;
 /**
  * How to filter the merged doc list.
  */

package/dist/plugins/route-pages-candidates.d.ts

@@ -0,0 +1,19 @@
+/**
+ * File extensions zfb's router accepts as `pages/` route sources. Mirrors
+ * the Rust-side single source of truth `zfb_types::ROUTABLE_PAGE_EXTENSIONS`
+ * (zfb crate `crates/zfb-types/src/page_extensions.rs`) — that constant is
+ * not importable from JS, so it is copied here deliberately; keep in sync if
+ * zfb ever changes its accepted extension list.
+ */
+export declare const ROUTABLE_PAGE_EXTENSIONS: readonly ["tsx", "ts", "jsx", "js", "mdx", "md", "html"];
+/**
+ * Derive every `pages/`-relative path that would shadow the given injected
+ * route pattern (a zfb `injectRoute` pattern string, e.g.
+ * `"/docs/tags/[tag]"` or `"/[locale]"`). Pure — no filesystem I/O; the
+ * caller probes each candidate against the host's real `pages/` dir.
+ *
+ * Returns `[]` for the empty/root pattern (`"/"`) — never produced by this
+ * plugin's route catalog (zfb rejects `injectRoute("/")` outright), so there
+ * is nothing meaningful to derive.
+ */
+export declare function derivePagesCandidates(pattern: string): string[];

package/dist/plugins/route-pages-candidates.js

@@ -0,0 +1,17 @@
+const ROUTABLE_PAGE_EXTENSIONS = ["tsx", "ts", "jsx", "js", "mdx", "md", "html"];
+function derivePagesCandidates(pattern) {
+  const segments = pattern.split("/").filter(Boolean);
+  if (segments.length === 0) return [];
+  const lastSegment = segments[segments.length - 1];
+  const dirPrefix = segments.length > 1 ? `${segments.slice(0, -1).join("/")}/` : "";
+  const candidates = [];
+  for (const ext of ROUTABLE_PAGE_EXTENSIONS) {
+    candidates.push(`${dirPrefix}${lastSegment}.${ext}`);
+    candidates.push(`${dirPrefix}${lastSegment}/index.${ext}`);
+  }
+  return candidates;
+}
+export {
+  ROUTABLE_PAGE_EXTENSIONS,
+  derivePagesCandidates
+};