@takazudo/zudo-doc 2.4.0 → 2.5.0

package/dist/header/header.js

@@ -6,6 +6,8 @@ import {
   pathForMatch
 } from "./nav-active.js";
 import { NAV_OVERFLOW_SCRIPT } from "./nav-overflow-script.js";
+import { LANGUAGE_SWITCHER_INIT_SCRIPT } from "../i18n-version/language-switcher.js";
+import { VERSION_SWITCHER_REWIRE_SCRIPT } from "../i18n-version/version-switcher.js";
 import { GitHub as GitHubIcon } from "../icons/index.js";
 function Header(props) {
   const {
@@ -25,6 +27,7 @@ function Header(props) {
     headerRightItems,
     colorModeEnabled,
     hasLocales,
+    hasVersions,
     githubRepoUrl,
     githubLabel,
     urlHelpers,
@@ -115,7 +118,31 @@ function Header(props) {
             ))
           }
         ),
-        /* @__PURE__ */ jsx("script", { dangerouslySetInnerHTML: { __html: NAV_OVERFLOW_SCRIPT } })
+        /* @__PURE__ */ jsx("script", { dangerouslySetInnerHTML: { __html: NAV_OVERFLOW_SCRIPT } }),
+        hasLocales ? (
+          // Keeps the persisted header's language-switcher hrefs pointing at the
+          // current page's equivalent in each other locale across same-locale SPA
+          // navigation (#2551). Registers a document-level AFTER_NAVIGATE_EVENT
+          // listener once; idempotent across re-execution.
+          /* @__PURE__ */ jsx(
+            "script",
+            {
+              dangerouslySetInnerHTML: { __html: LANGUAGE_SWITCHER_INIT_SCRIPT }
+            }
+          )
+        ) : null,
+        hasVersions ? (
+          // Keeps the persisted header's version-switcher menu hrefs / active row /
+          // trigger label tracking the current page across same-locale SPA
+          // navigation (#2553). Registers a document-level AFTER_NAVIGATE_EVENT
+          // listener once; idempotent across re-execution.
+          /* @__PURE__ */ jsx(
+            "script",
+            {
+              dangerouslySetInnerHTML: { __html: VERSION_SWITCHER_REWIRE_SCRIPT }
+            }
+          )
+        ) : null
       ]
     }
   );

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

@@ -23,6 +23,10 @@ export interface HeaderVersionEntry {
 /** Settings subset read by {@link createHeaderWithDefaults}. */
 export interface HeaderWithDefaultsSettings {
     siteName: string;
+    /** Site base path — fed to the language-switcher SPA re-wire config. */
+    base: string;
+    /** Trailing-slash policy — fed to the language-switcher SPA re-wire config. */
+    trailingSlash: boolean;
     headerNav: Array<{
         label: string;
         labelKey?: string;

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

@@ -97,14 +97,26 @@ function createHeaderWithDefaults(ctx) {
           versionsPageUrl,
           versionUrls,
           labels,
-          idSuffix: "header"
+          idSuffix: "header",
+          rewireConfig: {
+            base: settings.base.replace(/\/+$/, ""),
+            defaultLocale,
+            trailingSlash: settings.trailingSlash,
+            currentLocale: lang
+          }
         }
       );
     }
     const languageSwitcher = localeLinks != null ? /* @__PURE__ */ jsx(
       LanguageSwitcher,
       {
-        links: localeLinks
+        links: localeLinks,
+        config: {
+          base: settings.base.replace(/\/+$/, ""),
+          defaultLocale,
+          trailingSlash: settings.trailingSlash
+        },
+        currentLocale: lang
       }
     ) : void 0;
     const persistKey = `header-${lang}`;

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

@@ -1,7 +1,7 @@
-export { LanguageSwitcher } from "./language-switcher.js";
-export type { LanguageSwitcherProps } from "./language-switcher.js";
-export { VersionSwitcher, VERSION_SWITCHER_INIT_SCRIPT, VERSION_SWITCHER_VISIBILITY_STYLE, } from "./version-switcher.js";
-export type { VersionSwitcherProps } from "./version-switcher.js";
+export { LanguageSwitcher, LANGUAGE_SWITCHER_INIT_SCRIPT, switchLocaleHref, } from "./language-switcher.js";
+export type { LanguageSwitcherProps, LanguageSwitcherConfig, } from "./language-switcher.js";
+export { VersionSwitcher, VERSION_SWITCHER_INIT_SCRIPT, VERSION_SWITCHER_REWIRE_SCRIPT, VERSION_SWITCHER_VISIBILITY_STYLE, computeVersionSwitcherState, } from "./version-switcher.js";
+export type { VersionSwitcherProps, VersionSwitcherRewireConfig, VersionSwitcherState, } from "./version-switcher.js";
 export { VersionBanner } from "./version-banner.js";
 export type { VersionBannerProps, VersionBannerLabels } from "./version-banner.js";
 export type { LocaleLink, VersionEntry, VersionSwitcherLabels, } from "./types.js";

package/dist/i18n-version/index.js

@@ -1,14 +1,24 @@
-import { LanguageSwitcher } from "./language-switcher.js";
+import {
+  LanguageSwitcher,
+  LANGUAGE_SWITCHER_INIT_SCRIPT,
+  switchLocaleHref
+} from "./language-switcher.js";
 import {
   VersionSwitcher,
   VERSION_SWITCHER_INIT_SCRIPT,
-  VERSION_SWITCHER_VISIBILITY_STYLE
+  VERSION_SWITCHER_REWIRE_SCRIPT,
+  VERSION_SWITCHER_VISIBILITY_STYLE,
+  computeVersionSwitcherState
 } from "./version-switcher.js";
 import { VersionBanner } from "./version-banner.js";
 export {
+  LANGUAGE_SWITCHER_INIT_SCRIPT,
   LanguageSwitcher,
   VERSION_SWITCHER_INIT_SCRIPT,
+  VERSION_SWITCHER_REWIRE_SCRIPT,
   VERSION_SWITCHER_VISIBILITY_STYLE,
   VersionBanner,
-  VersionSwitcher
+  VersionSwitcher,
+  computeVersionSwitcherState,
+  switchLocaleHref
 };

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

@@ -2,6 +2,46 @@
 /** @jsxImportSource preact */
 import type { VNode } from "preact";
 import type { LocaleLink } from "./types.js";
+/**
+ * The minimal project config the client re-wire needs to reproduce
+ * `getPathForLocale`'s output from the live pathname. Emitted as `data-*`
+ * attributes on the switcher container so {@link LANGUAGE_SWITCHER_INIT_SCRIPT}
+ * can read it without any serialized props.
+ */
+export interface LanguageSwitcherConfig {
+    /** Normalized site base with no trailing slash (`""` for a root site). */
+    base: string;
+    /** The project's default locale (rendered without a locale prefix). */
+    defaultLocale: string;
+    /** Whether the project appends trailing slashes to page URLs. */
+    trailingSlash: boolean;
+}
+/**
+ * Client-side re-computation of a locale-switched href from the *current*
+ * pathname. This is a self-contained port of `getPathForLocale` (+ its
+ * `stripBase` / version-prefix split / `withBase` / `applyTrailingSlash`
+ * dependencies) from `url-helpers`. It MUST stay behaviourally identical to
+ * that function — pinned by the drift-guard test in
+ * `__tests__/language-switcher.test.tsx`, which asserts equality against the
+ * real `buildLocaleLinks` output across a case table.
+ *
+ * It is deliberately self-contained (no references to module-scope helpers)
+ * because {@link LANGUAGE_SWITCHER_INIT_SCRIPT} embeds it verbatim via
+ * `.toString()`, so it must be valid as a standalone function in the browser.
+ */
+export declare function switchLocaleHref(pathname: string, config: LanguageSwitcherConfig, currentLang: string, targetLang: string): string;
+/**
+ * Inline init script that keeps the switcher's per-page hrefs correct inside a
+ * persisted header. Mounted once wherever a header is rendered (see
+ * `header.tsx`), it registers a document-level `zfb:after-swap` listener on
+ * first load and re-runs {@link switchLocaleHref} against the live pathname —
+ * the same rebind-on-navigate contract `VERSION_SWITCHER_INIT_SCRIPT` uses.
+ *
+ * `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.
+ */
+export declare const LANGUAGE_SWITCHER_INIT_SCRIPT: string;
 export interface LanguageSwitcherProps {
     /**
      * Pre-built locale links, ordered as they should appear in the bar.
@@ -9,6 +49,19 @@ export interface LanguageSwitcherProps {
      * `buildLocaleLinks(currentPath, currentLang)` helper before passing.
      */
     links: LocaleLink[];
+    /**
+     * When provided, the switcher container emits `data-*` config so
+     * {@link LANGUAGE_SWITCHER_INIT_SCRIPT} can re-compute each anchor's href
+     * from the live pathname after a same-locale SPA navigation (the header is
+     * persisted, so SSR hrefs would otherwise go stale). Omit for a purely
+     * static / no-JS render.
+     */
+    config?: LanguageSwitcherConfig;
+    /**
+     * The active locale code, recorded as `data-current-locale` so the re-wire
+     * script knows which locale segment to strip. Only read when `config` is set.
+     */
+    currentLocale?: string;
 }
 /**
  * Inline locale switcher rendered in the header / sidebar footer.
@@ -17,5 +70,5 @@ export interface LanguageSwitcherProps {
  * template's `localeLinks.length > 1 &&` guard so call-sites can mount
  * the component unconditionally).
  */
-export declare function LanguageSwitcher({ links }: LanguageSwitcherProps): VNode | null;
+export declare function LanguageSwitcher({ links, config, currentLocale, }: LanguageSwitcherProps): VNode | null;
 export type { LocaleLink };

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

@@ -1,8 +1,83 @@
 import { jsx, jsxs } from "preact/jsx-runtime";
 import { Fragment } from "preact";
-function LanguageSwitcher({ links }) {
+import { AFTER_NAVIGATE_EVENT } from "../transitions/index.js";
+function switchLocaleHref(pathname, config, currentLang, targetLang) {
+  const normalizedBase = config.base;
+  const defaultLocale = config.defaultLocale;
+  const trailingSlash = config.trailingSlash;
+  const stripBase = (path) => {
+    if (normalizedBase === "") return path;
+    if (path === normalizedBase) return "/";
+    return path.indexOf(normalizedBase + "/") === 0 ? path.slice(normalizedBase.length) : path;
+  };
+  const applyTrailingSlash = (url) => {
+    if (!trailingSlash) return url;
+    if (url.charAt(url.length - 1) === "/") return url;
+    const suffixIdx = url.search(/[?#]/);
+    const pathPart = suffixIdx >= 0 ? url.slice(0, suffixIdx) : url;
+    const suffix = suffixIdx >= 0 ? url.slice(suffixIdx) : "";
+    if (pathPart.charAt(pathPart.length - 1) === "/") return url;
+    const segments = pathPart.split("/");
+    const lastSegment = segments[segments.length - 1] || "";
+    if (/\.[a-zA-Z]\w*$/.test(lastSegment)) return url;
+    return pathPart + "/" + suffix;
+  };
+  const withBase = (path) => {
+    const raw = normalizedBase === "" ? path : normalizedBase + (path.charAt(0) === "/" ? path : "/" + path);
+    return applyTrailingSlash(raw);
+  };
+  const stripped = stripBase(pathname);
+  const versionMatch = stripped.match(/^(\/v\/[^/]+)(\/.*|$)/);
+  const versionPrefix = versionMatch ? versionMatch[1] || "" : "";
+  let relativePath = versionMatch ? versionMatch[2] || "/" : stripped;
+  if (currentLang !== defaultLocale) {
+    relativePath = relativePath.replace(
+      new RegExp("^/" + currentLang + "(?:/|$)"),
+      "/"
+    );
+  }
+  if (targetLang !== defaultLocale) {
+    relativePath = "/" + targetLang + relativePath;
+  }
+  return withBase(versionPrefix + relativePath);
+}
+const LANGUAGE_SWITCHER_INIT_SCRIPT = `(function(){
+var FLAG="__zdLanguageSwitcherInit";
+if(window[FLAG])return;
+window[FLAG]=true;
+var switchLocaleHref=${switchLocaleHref.toString()};
+function rewire(){
+var containers=document.querySelectorAll("[data-language-switcher]");
+for(var i=0;i<containers.length;i++){
+var c=containers[i];
+var config={base:c.getAttribute("data-base")||"",defaultLocale:c.getAttribute("data-default-locale")||"",trailingSlash:c.getAttribute("data-trailing-slash")==="true"};
+var currentLang=c.getAttribute("data-current-locale")||config.defaultLocale;
+var anchors=c.querySelectorAll("a[lang]");
+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));
+}
+}
+}
+rewire();
+document.addEventListener(${JSON.stringify(AFTER_NAVIGATE_EVENT)},rewire);
+})();`;
+function LanguageSwitcher({
+  links,
+  config,
+  currentLocale
+}) {
   if (links.length <= 1) return null;
-  return /* @__PURE__ */ jsx("div", { class: "flex items-center gap-x-hsp-xs text-small", children: links.map((link, i) => (
+  const rewireAttrs = config ? {
+    "data-language-switcher": true,
+    "data-base": config.base,
+    "data-default-locale": config.defaultLocale,
+    "data-trailing-slash": String(config.trailingSlash),
+    "data-current-locale": currentLocale ?? config.defaultLocale
+  } : {};
+  return /* @__PURE__ */ jsx("div", { class: "flex items-center gap-x-hsp-xs text-small", ...rewireAttrs, children: links.map((link, i) => (
     // Fragment is keyed via the locale code so the reconciler keeps
     // the active/inactive nodes paired correctly across re-renders
     // (e.g. when the active locale flips after navigation).
@@ -21,5 +96,7 @@ function LanguageSwitcher({ links }) {
   )) });
 }
 export {
-  LanguageSwitcher
+  LANGUAGE_SWITCHER_INIT_SCRIPT,
+  LanguageSwitcher,
+  switchLocaleHref
 };

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

@@ -38,7 +38,66 @@ export interface VersionSwitcherProps {
      * unique.
      */
     idSuffix?: string;
+    /**
+     * When provided, the switcher container emits `data-version-rewire` plus its
+     * config as `data-*`, and the menu anchors / trigger label carry the marker
+     * attributes {@link VERSION_SWITCHER_REWIRE_SCRIPT} needs. This lets the
+     * script recompute the per-page menu hrefs + active state + trigger label
+     * from the live pathname after a same-locale SPA navigation — the header is
+     * persisted (`data-zfb-transition-persist="header-${lang}"`), so its SSR menu
+     * values would otherwise go stale (zudolab/zudo-doc#2553).
+     *
+     * Omit for a static / no-JS render, e.g. the inline breadcrumb switcher,
+     * which lives in swapped content and is re-rendered fresh on every swap.
+     */
+    rewireConfig?: VersionSwitcherRewireConfig;
+}
+/**
+ * The minimal project config the client re-wire needs to reproduce the header
+ * factory's per-page menu URLs from the live pathname. Emitted as `data-*`
+ * attributes on the switcher container so {@link VERSION_SWITCHER_REWIRE_SCRIPT}
+ * can read it without any serialized props.
+ */
+export interface VersionSwitcherRewireConfig {
+    /** Normalized site base with no trailing slash (`""` for a root site). */
+    base: string;
+    /** The project's default locale (rendered without a locale prefix). */
+    defaultLocale: string;
+    /** Whether the project appends trailing slashes to page URLs. */
+    trailingSlash: boolean;
+    /**
+     * The active locale code — constant within a `header-${lang}` persist window,
+     * so it can be read once from the SSR container rather than re-derived.
+     */
+    currentLocale: string;
+}
+/** The re-computed per-page menu state {@link computeVersionSwitcherState} returns. */
+export interface VersionSwitcherState {
+    /** Href for the "Latest" entry, matching the SSR `latestUrl`. */
+    latestHref: string;
+    /** version slug → href for that version of the current page (SSR `versionUrls`). */
+    versionHrefs: Record<string, string>;
+    /** Active version slug, or `null` when the current page is on "latest". */
+    activeVersion: string | null;
 }
+/**
+ * Client-side re-computation of the version-switcher's per-page menu state from
+ * the *current* pathname. This is a self-contained port of the header factory's
+ * URL logic (`createHeaderWithDefaults`'s `latestUrl` / `versionUrls` block, in
+ * turn `docsUrl` / `versionedDocsUrl` / `withBase` from `url-helpers`). It MUST
+ * stay behaviourally identical to that SSR path — pinned by the drift-guard test
+ * in `__tests__/version-switcher.test.tsx`, which asserts equality against the
+ * real `makeUrlHelpers` output across a case table.
+ *
+ * It is deliberately self-contained (no references to module-scope helpers)
+ * because {@link VERSION_SWITCHER_REWIRE_SCRIPT} embeds it verbatim via
+ * `.toString()`, so it must be valid as a standalone function in the browser.
+ *
+ * The `/docs/versions` listing is a standalone package route (`currentSlug`
+ * `undefined` on the SSR side), so — like the SSR factory — every menu href
+ * there collapses to `versionsPageUrl`; the exact-path check below mirrors that.
+ */
+export declare function computeVersionSwitcherState(pathname: string, config: VersionSwitcherRewireConfig, versionSlugs: string[]): VersionSwitcherState;
 /**
  * Canonical CSS rule that backs the responsive visibility of the
  * version-switcher's host wrapper. **The component itself does NOT
@@ -98,4 +157,21 @@ export declare function VersionSwitcher(props: VersionSwitcherProps): VNode;
  * vocabulary swap.
  */
 export declare const VERSION_SWITCHER_INIT_SCRIPT: string;
+/**
+ * Inline script that keeps the switcher's per-page menu correct inside a
+ * persisted header. Mounted once wherever a header renders a re-wireable
+ * VersionSwitcher (see `header.tsx`, gated on `hasVersions`), it recomputes each
+ * menu anchor's href, the active row, and the trigger label from the live
+ * pathname on first load and on `zfb:after-swap` — the same rebind-on-navigate
+ * contract `LANGUAGE_SWITCHER_INIT_SCRIPT` uses (zudolab/zudo-doc#2553).
+ *
+ * It only touches switchers carrying `data-version-rewire` (emitted when a
+ * {@link VersionSwitcherRewireConfig} is passed), so the inline breadcrumb
+ * switcher — re-rendered fresh on every swap — is left alone.
+ *
+ * `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.
+ */
+export declare const VERSION_SWITCHER_REWIRE_SCRIPT: string;
 export type { VersionEntry, VersionSwitcherLabels };

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

@@ -1,5 +1,64 @@
 import { jsx, jsxs } from "preact/jsx-runtime";
 import { AFTER_NAVIGATE_EVENT } from "../transitions/page-events.js";
+function computeVersionSwitcherState(pathname, config, versionSlugs) {
+  const normalizedBase = config.base;
+  const defaultLocale = config.defaultLocale;
+  const currentLocale = config.currentLocale;
+  const trailingSlash = config.trailingSlash;
+  const stripBase = (path) => {
+    if (normalizedBase === "") return path;
+    if (path === normalizedBase) return "/";
+    return path.indexOf(normalizedBase + "/") === 0 ? path.slice(normalizedBase.length) : path;
+  };
+  const applyTrailingSlash = (url) => {
+    if (!trailingSlash) return url;
+    if (url.charAt(url.length - 1) === "/") return url;
+    const suffixIdx = url.search(/[?#]/);
+    const pathPart = suffixIdx >= 0 ? url.slice(0, suffixIdx) : url;
+    const suffix = suffixIdx >= 0 ? url.slice(suffixIdx) : "";
+    if (pathPart.charAt(pathPart.length - 1) === "/") return url;
+    const segments = pathPart.split("/");
+    const lastSegment = segments[segments.length - 1] || "";
+    if (/\.[a-zA-Z]\w*$/.test(lastSegment)) return url;
+    return pathPart + "/" + suffix;
+  };
+  const withBase = (path) => {
+    const raw = normalizedBase === "" ? path : normalizedBase + (path.charAt(0) === "/" ? path : "/" + path);
+    return applyTrailingSlash(raw);
+  };
+  const versionsPageUrl = withBase(
+    currentLocale === defaultLocale ? "/docs/versions" : "/" + currentLocale + "/docs/versions"
+  );
+  const stripped = stripBase(pathname);
+  const versionMatch = stripped.match(/^\/v\/([^/]+)(\/.*|$)/);
+  const rest = versionMatch ? versionMatch[2] || "/" : stripped;
+  let localeStripped = rest;
+  if (currentLocale !== defaultLocale) {
+    localeStripped = rest.replace(
+      new RegExp("^/" + currentLocale + "(?:/|$)"),
+      "/"
+    );
+  }
+  const isVersionsIndex = localeStripped === "/docs/versions" || localeStripped === "/docs/versions/";
+  const isDocPage = /^\/docs(\/|$)/.test(localeStripped) && !isVersionsIndex;
+  const activeVersion = isDocPage && versionMatch ? versionMatch[1] || null : null;
+  const versionHrefs = {};
+  let latestHref;
+  if (isDocPage) {
+    latestHref = withBase(rest);
+    for (let i = 0; i < versionSlugs.length; i++) {
+      const slug = versionSlugs[i];
+      if (slug) versionHrefs[slug] = withBase("/v/" + slug + rest);
+    }
+  } else {
+    latestHref = versionsPageUrl;
+    for (let i = 0; i < versionSlugs.length; i++) {
+      const slug = versionSlugs[i];
+      if (slug) versionHrefs[slug] = versionsPageUrl;
+    }
+  }
+  return { latestHref, versionHrefs, activeVersion };
+}
 function cls(...parts) {
   return parts.filter(Boolean).join(" ");
 }
@@ -34,12 +93,21 @@ function VersionSwitcher(props) {
     versionUrls,
     unavailableVersions,
     labels,
-    idSuffix = ""
+    idSuffix = "",
+    rewireConfig
   } = props;
   const menuId = `version-menu${idSuffix ? `-${idSuffix}` : ""}`;
   const isLatest = !currentVersion;
   const triggerLabel = isLatest ? labels.latest : versions.find((v) => v.slug === currentVersion)?.label ?? currentVersion;
-  return /* @__PURE__ */ jsxs("div", { class: "version-switcher relative", "data-version-switcher": true, children: [
+  const rewire = rewireConfig != null;
+  const rewireAttrs = rewireConfig ? {
+    "data-version-rewire": true,
+    "data-base": rewireConfig.base,
+    "data-default-locale": rewireConfig.defaultLocale,
+    "data-trailing-slash": String(rewireConfig.trailingSlash),
+    "data-current-locale": rewireConfig.currentLocale
+  } : {};
+  return /* @__PURE__ */ jsxs("div", { class: "version-switcher relative", "data-version-switcher": true, ...rewireAttrs, children: [
     /* @__PURE__ */ jsxs(
       "button",
       {
@@ -53,7 +121,14 @@ function VersionSwitcher(props) {
             labels.switcher,
             ":"
           ] }),
-          /* @__PURE__ */ jsx("span", { class: "font-medium", children: triggerLabel }),
+          /* @__PURE__ */ jsx(
+            "span",
+            {
+              class: "font-medium",
+              "data-version-trigger-label": rewire ? true : void 0,
+              children: triggerLabel
+            }
+          ),
           /* @__PURE__ */ jsx(ChevronDownIcon, {})
         ]
       }
@@ -74,6 +149,7 @@ function VersionSwitcher(props) {
                 "block px-hsp-md py-vsp-2xs text-small hover:bg-accent/10 hover:underline focus-visible:underline",
                 isLatest ? "font-bold text-accent" : "text-fg"
               ),
+              "data-version-latest": rewire ? true : void 0,
               children: labels.latest
             }
           ) }),
@@ -90,6 +166,7 @@ function VersionSwitcher(props) {
                   "block px-hsp-md py-vsp-2xs text-small hover:bg-accent/10 hover:underline focus-visible:underline",
                   isActive ? "font-bold text-accent" : "text-fg"
                 ),
+                "data-version-slug": rewire ? v.slug : void 0,
                 children: v.label
               }
             ) : /* @__PURE__ */ jsx(
@@ -100,6 +177,7 @@ function VersionSwitcher(props) {
                 tabindex: -1,
                 class: "block px-hsp-md py-vsp-2xs text-small text-muted/50 cursor-not-allowed pointer-events-none",
                 title: labels.unavailable,
+                "data-version-slug": rewire ? v.slug : void 0,
                 children: v.label
               }
             ) }, v.slug);
@@ -150,8 +228,63 @@ toggle.focus();
 initVersionSwitcher();
 document.addEventListener(${JSON.stringify(AFTER_NAVIGATE_EVENT)},initVersionSwitcher);
 })();`;
+const VERSION_SWITCHER_REWIRE_SCRIPT = `(function(){
+var FLAG="__zdVersionSwitcherRewire";
+if(window[FLAG])return;
+window[FLAG]=true;
+var computeVersionSwitcherState=${computeVersionSwitcherState.toString()};
+function setActive(a,active){
+a.classList.toggle("font-bold",active);
+a.classList.toggle("text-accent",active);
+a.classList.toggle("text-fg",!active);
+if(active){a.setAttribute("aria-current","page");}else{a.removeAttribute("aria-current");}
+}
+function rewire(){
+var containers=document.querySelectorAll("[data-version-rewire]");
+for(var i=0;i<containers.length;i++){
+var c=containers[i];
+var config={base:c.getAttribute("data-base")||"",defaultLocale:c.getAttribute("data-default-locale")||"",trailingSlash:c.getAttribute("data-trailing-slash")==="true",currentLocale:c.getAttribute("data-current-locale")||""};
+var versionAnchors=c.querySelectorAll("[data-version-slug]");
+var slugs=[];
+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 latest=c.querySelector("[data-version-latest]");
+if(latest){
+latest.setAttribute("href",state.latestHref);
+setActive(latest,state.activeVersion===null);
+}
+for(var k=0;k<versionAnchors.length;k++){
+var a=versionAnchors[k];
+var slug=a.getAttribute("data-version-slug");
+if(!slug)continue;
+var href=state.versionHrefs[slug];
+if(href!=null)a.setAttribute("href",href);
+if(!a.hasAttribute("aria-disabled"))setActive(a,state.activeVersion===slug);
+}
+var label=c.querySelector("[data-version-trigger-label]");
+if(label){
+if(state.activeVersion===null){
+if(latest)label.textContent=latest.textContent;
+}else{
+var activeLabel=null;
+for(var m=0;m<versionAnchors.length;m++){
+if(versionAnchors[m].getAttribute("data-version-slug")===state.activeVersion){activeLabel=versionAnchors[m].textContent;break;}
+}
+label.textContent=activeLabel!=null?activeLabel:state.activeVersion;
+}
+}
+}
+}
+rewire();
+document.addEventListener(${JSON.stringify(AFTER_NAVIGATE_EVENT)},rewire);
+})();`;
 export {
   VERSION_SWITCHER_INIT_SCRIPT,
+  VERSION_SWITCHER_REWIRE_SCRIPT,
   VERSION_SWITCHER_VISIBILITY_STYLE,
-  VersionSwitcher
+  VersionSwitcher,
+  computeVersionSwitcherState
 };

package/dist/integrations/claude-resources/generate.js

@@ -97,11 +97,14 @@ function downgradeRepoRelativeLinks(content) {
 function findClaudeMdFiles(dir, excludeDirs) {
   const results = [];
   if (!fs.existsSync(dir)) return results;
+  const excludes = excludeDirs.map(
+    (d) => d.endsWith(path.sep) ? d.slice(0, -path.sep.length) : d
+  );
   for (const item of fs.readdirSync(dir)) {
     if (item === "node_modules") continue;
     if (item.startsWith(".")) continue;
     const itemPath = path.join(dir, item);
-    if (excludeDirs.some((d) => itemPath.startsWith(d))) continue;
+    if (excludes.some((d) => itemPath === d || itemPath.startsWith(d + path.sep))) continue;
     let stat;
     try {
       stat = fs.lstatSync(itemPath);
@@ -109,7 +112,7 @@ function findClaudeMdFiles(dir, excludeDirs) {
       continue;
     }
     if (stat.isDirectory()) {
-      results.push(...findClaudeMdFiles(itemPath, excludeDirs));
+      results.push(...findClaudeMdFiles(itemPath, excludes));
     } else if (stat.isFile() && item === "CLAUDE.md") {
       results.push(itemPath);
     }

package/dist/integrations/claude-resources/index.d.ts

@@ -12,10 +12,27 @@ export interface ClaudeResourcesPluginOptions {
      */
     claudeDir: string;
     /**
-     * Project root used both as the search root for `CLAUDE.md` discovery
-     * and to anchor relative paths. Defaults to `process.cwd()`.
+     * Anchor for resolving the relative `claudeDir`, `docsDir`, and `scanRoot`
+     * paths, and the default value of `scanRoot`. Defaults to `process.cwd()`.
+     *
+     * Note: this does NOT itself decide where `CLAUDE.md` discovery walks — that
+     * is `scanRoot` (which defaults to this). Set `scanRoot` to widen discovery
+     * (e.g. a subdirectory doc site scanning its repo root) without moving the
+     * output base, which stays anchored here.
      */
     projectRoot?: string;
+    /**
+     * Root for `CLAUDE.md` discovery and the base for the generated pages'
+     * relative-path titles/slugs. Defaults to `projectRoot`. Resolved against
+     * `projectRoot` when relative (absolute allowed).
+     *
+     * Scope: governs `CLAUDE.md` discovery ONLY. Commands, skills, and agents
+     * always come from `claudeDir` and are unaffected by `scanRoot`. Decoupling
+     * this from `projectRoot` lets a doc site in a repo subdirectory scan
+     * repo-wide `CLAUDE.md` files while still writing generated pages into its
+     * own content collection (see #2558).
+     */
+    scanRoot?: string;
     /**
      * Output directory for generated MDX pages, resolved against
      * `projectRoot` when relative. Defaults to `src/content/docs` to

package/dist/integrations/claude-resources/index.js

@@ -12,9 +12,10 @@ function claudeResourcesPlugin(options) {
 function runClaudeResourcesPreStep(options) {
   const projectRoot = path.resolve(options.projectRoot ?? process.cwd());
   const claudeDir = path.isAbsolute(options.claudeDir) ? options.claudeDir : path.resolve(projectRoot, options.claudeDir);
+  const scanRoot = options.scanRoot === void 0 ? projectRoot : path.isAbsolute(options.scanRoot) ? options.scanRoot : path.resolve(projectRoot, options.scanRoot);
   const docsDirInput = options.docsDir ?? "src/content/docs";
   const docsDir = path.isAbsolute(docsDirInput) ? docsDirInput : path.resolve(projectRoot, docsDirInput);
-  return generateClaudeResourcesDocs({ claudeDir, projectRoot, docsDir });
+  return generateClaudeResourcesDocs({ claudeDir, projectRoot: scanRoot, docsDir });
 }
 export {
   CLAUDE_RESOURCES_PLUGIN_NAME,

package/dist/plugins/claude-resources.js

@@ -10,10 +10,12 @@ const plugin = {
       );
     }
     const projectRootOpt = ctx.options["projectRoot"];
+    const scanRootOpt = ctx.options["scanRoot"];
     const docsDirOpt = ctx.options["docsDir"];
     const result = await runClaudeResourcesPreStep({
       claudeDir,
       projectRoot: typeof projectRootOpt === "string" ? projectRootOpt : ctx.projectRoot,
+      scanRoot: typeof scanRootOpt === "string" ? scanRootOpt : void 0,
       docsDir: typeof docsDirOpt === "string" ? docsDirOpt : "src/content/docs"
     });
     ctx.logger.info(

package/dist/preset.d.ts

@@ -50,6 +50,11 @@ export interface PresetVersionConfig {
 export interface PresetClaudeResourcesConfig {
     claudeDir: string;
     projectRoot?: string;
+    /**
+     * Root for `CLAUDE.md` discovery; defaults to `projectRoot`. Decouples
+     * repo-wide scanning from the output base for subdirectory doc sites (#2558).
+     */
+    scanRoot?: string;
 }
 /**
  * The subset of `settings` the preset reads. Any concrete `typeof settings`

package/dist/preset.js

@@ -171,6 +171,7 @@ function buildPlugins(settings, routeContext) {
         options: {
           claudeDir: settings.claudeResources.claudeDir,
           projectRoot: settings.claudeResources.projectRoot,
+          scanRoot: settings.claudeResources.scanRoot,
           docsDir: settings.docsDir
         }
       }

package/dist/safelist.css

@@ -1,2 +1,2 @@
 /* generated by gen-safelist.mjs — do not edit by hand */
-@source inline("-link -mb-px -ml-hsp-sm -noscript -translate-x-full 2xl:w-[24px] [&::-webkit-details-marker]:hidden [&_a]:text-accent [&_a]:underline [&_nav]:mb-0 [data-admonition] [data-kbd-shortcut] [doc-history-meta] [doc-history] [doc-layout] [llms-txt] a a2 abbr about above absent absolute accent across activated active actual added admonition admonition- admonition-body admonition-title admonition/callout after after-breadcrumb after-content after-navigate after-sidebar after-title against agent agents ai-chat ai-chat-md ai-chat-trigger alert align-top all allow-same-origin allow-scripts alone already already-executed already-picked an anchor anchored and and/or animate-spin announce antialiased any application/json application/xml applies apply-css-vars approach are area arg aria-atomic aria-busy aria-controls aria-current aria-disabled aria-expanded aria-haspopup aria-hidden aria-label aria-live aria-orientation aria-pressed aria-selected aria-valuemax aria-valuemin aria-valuenow arm arms arrows article as asc aside aspect-[1200/630] aspect-square asset- assets assistant async at attach attribute attributes auto autogenerated available avoid await away b back backdrop:bg-bg/30 backdrop:bg-bg/80 backdrop:bg-overlay/60 backdrop:z-modal-backdrop background background-color backtick backticks baked banner bare base base64 based batch be because before below best between bg bg-[#fff] bg-accent bg-bg bg-chat-assistant-bg bg-chat-user-bg bg-code-bg bg-fg bg-info/10 bg-info/5 bg-muted bg-overlay/30 bg-surface bg-transparent bg-warning/10 bg-warning/5 bi bigint bin blank blanks blob block blockquote blocks blur body body-end-components body-end-scripts bold boolean bootstrap border border-accent border-b border-b-2 border-b-[5px] border-bg/30 border-collapse border-danger border-dashed border-fg border-info/30 border-l border-l-0 border-l-[3px] border-left-width border-muted border-none border-r border-radius border-solid border-t border-t-[2px] border-t-[3px] border-transparent border-warning/30 border-width border-y both bottom-vsp-xl box-border br brand breadcrumb:end breadcrumb:start break-words browser browsers btn bug build bundler but button buttons by bypassed byte-identical bytes cached call caller calls can cancellation cannot canonical canvas caption card card-grid carry cases cat-nav- catch category catppuccin-latte caught caution center center/contain ch chains change changed changes checkbox child chrome ci circle cite class class-less claude claude-agents claude-commands claude-md claude-skills cleaned clear clear-css-vars clearing click client client-router client-side clip clobbering close closed closing code code-block-sr-announce code-group code-group-panel col col-resize colgroup collision color color-scheme color-scheme-changed color-scheme-provider color-tweak colorization colors column comma command commands comment commit compare component component:github-link component:language-switcher component:search component:theme-toggle component:version-switcher compute computed concrete configuration configure configured confuse connect const construction consumer consumes container containers containing content content-admonition content-link content-type content-wrapper:end content-wrapper:start contents context controller controls converts copy corners correct correctly corrupt count covered covers cp crashes created cross-component crumb- cs css ctx cur current cursor cursor-not-allowed cursor-pointer custom danger dark data data-active data-admonition data-base data-close-search data-group-id data-header data-header-logo data-header-nav data-header-right data-kbd-shortcut data-loading-index data-mermaid-enlarge-ready data-mermaid-rendered data-mermaid-src data-nav-active data-nav-item data-nav-item-dropdown data-nav-more data-nav-more-menu data-nav-more-toggle data-no-results data-open-search data-pan-active data-processed data-result-count-template data-search-count data-search-count-narrow data-search-dialog data-search-input data-search-placeholder data-search-results data-search-unavailable data-sidebar-hidden data-sidebar-resizer data-site-nav data-tab-btn data-tab-default data-tab-label data-tab-value data-tabs data-taglist-group data-testid data-theme data-theme/style data-variant data-version-banner data-version-menu data-version-switcher data-version-toggle data-zd-nosidebar data-zd-toc data-zfb-transition-persist dd decimal declare decoration decoration-muted default defaults del delegated dependency depth desc description design design-token-panel design-token-trigger desktop desktop-sidebar desktop-sidebar-toggle desktop-sidebar-toggle-island destructive detach detached details deterministic develop dfn diagram diagrams dialog dieser diff diff-line-added diff-line-content diff-line-empty diff-line-num diff-line-removed diff-row dir directly directories directory disabled disabled:opacity-50 disc display:none dist distinct div dl do doc doc-card- doc-content-band doc-history doc-history-generate doc-history-panel doc-history-trigger doc-page doc-pager doc-prose doc-title docs docs- docs-v- document document-level documented does double-registration drag draggable drop dropdown dropdown-child dropdown-parent dropdowns dt duration-150 duration-200 during dynamically e2e each ease-in-out edge eject ejected el element elements els else em embedded emit emitting empty empty/undefined en enable end enlarged entire entities entries entry error escape escaped even eventually every exactly excerpt excludes existing exists exit expected export extends factories failed fall fallback fallbacks falls false family fast feature feed fg fields fieldset figcaption figure file fill fills finally find fire fires first fixed fixed-width fixtures flag flash flat flex flex-1 flex-col flex-wrap flip flipping flips flush-left focus focus-visible:outline-2 focus-visible:outline-accent focus-visible:outline-offset-2 focus-visible:underline focus:border-accent focus:outline-none focus:underline font font-bold font-family font-medium font-mono font-semibold font-weight footer footer- for form found free fresh from frontmatter frontmatter-preview frozen fs-extra full fully function further g gap-[0.3em] gap-[clamp(1.5rem,3vw,4rem)] gap-hsp-2xs gap-hsp-md gap-hsp-sm gap-hsp-xl gap-hsp-xs gap-vsp-2xs gap-vsp-lg gap-vsp-md gap-vsp-xs gap-x-hsp-2xs gap-x-hsp-lg gap-x-hsp-md gap-x-hsp-sm gap-x-hsp-xs gap-y-vsp-2xs gap-y-vsp-lg gap-y-vsp-md gap-y-vsp-xs gaps gate generate generation genuine geometry get github github-link go got graph gray-matter grid grid-cols-1 grid-cols-2 group group-focus-visible:text-accent group-focus-visible:underline group-focus-within:block group-hover:bg-fg group-hover:block group-hover:text-accent group-hover:text-bg group-hover:underline group-open:rotate-90 guard h-[0.5rem] h-[0.625rem] h-[0.875rem] h-[1.125rem] h-[1.25rem] h-[1.575rem] h-[14px] h-[1em] h-[1lh] h-[2rem] h-[3.5rem] h-[3rem] h-[90vh] h-[calc(100%-3rem)] h-[calc(100vh-3.5rem)] h-dvh h-full h-icon-lg h-icon-md h-icon-sm h-icon-xs h1 h1s h2 h2s h3 h4 h5 h6 half hand hand-copied handle handled handler handlers has hash-link have head head-links head-scripts header header- header-call:end header-call:start heading heading-h2 heading-h3 heading-h4 headings height here hex hidden highlight highlighter history hit horizontal host hover:bg-[color-mix(in_srgb,var(--color-surface)_80%,var(--color-fg)_20%)] hover:bg-accent-hover hover:bg-accent/10 hover:bg-surface hover:border-accent hover:border-accent-hover hover:border-fg hover:text-accent hover:text-accent-hover hover:text-fg hover:underline hr href hrefs html i i18n/theme. i2 i3 i4 icon identical idle idx if iframe image image-enlarge image/png img implementation import important imports in inactive inbox includes index info inherit inherited initial initialised injected inline inline-block inline-flex inner input input-clear ins inset-0 inside install instance instanceof instead instructions intended intent into invalid inverse inversion invoke is issues it italic item item- items items-baseline items-center items-start its itself javascript justify-between justify-center justify-end justify-start katex kbd keep keeps kept keyboard keyboard-shortcut keydown keystroke keywords khroma label landing language-switcher last:border-b-0 later launch layout leading-relaxed leading-snug leading-tight leaf- leak leaves leaving left left-0 left:calc legend legitimate letter-spacing lg lg:block lg:border lg:border-fg lg:border-solid lg:flex lg:flex-col lg:flex-row lg:gap-hsp-xl lg:grid-cols-[repeat(auto-fit,minmax(12rem,1fr))] lg:h-[90vh] lg:hidden lg:justify-start lg:m-auto lg:max-h-[90vh] lg:max-w-[52.5rem] lg:ml-[var(--zd-sidebar-w)] lg:pt-vsp-2xl lg:px-hsp-2xl lg:py-vsp-2xl lg:text-left lg:w-[90vw] lg:w-[clamp(16rem,25%,22rem)] li li2 library light like likely line linger link link- links list-disc list-none listener literal literals lives llms llms-txt load local locale locales log longest-match look lostpointercapture lower luminance m m-0 m21 m6 main make malformed malicious maps mark marks matches matching math math-display math-inline max max-h-[80vh] max-h-[85vh] max-h-[90vh] max-h-full max-h-none max-w-[46rem] max-w-[85%] max-w-[85vw] max-w-[90vw] max-w-[clamp(50rem,75vw,90rem)] max-w-full max-w-none max-width may mb-0 mb-vsp-2xs mb-vsp-lg mb-vsp-md mb-vsp-sm mb-vsp-xl mb-vsp-xs measures measuring mechanism menu merged mermaid message messages meta meta-knob metadata migration min-h-[60vh] min-h-[calc(100vh-3.5rem)] min-h-screen min-w-0 min-w-[10rem] min-w-[8rem] mirror mirrors missing ml-auto ml-hsp-2xl ml-hsp-lg ml-hsp-sm ml-hsp-xl mod mode module mounted mouseenter mouseleave mr-hsp-sm mt-0 mt-vsp-2xl mt-vsp-2xs mt-vsp-3xs mt-vsp-lg mt-vsp-md mt-vsp-sm mt-vsp-xl must mutates mutation mutations mx-auto my-vsp-lg my-vsp-md name named native nav nav-active nav-card- nav/doc navigating navigation navigations near needs nested new newly-swapped next no no-enlarge no-op no-repeat no-underline node node:buffer node:fs node:fs/promises node:module node:path nodes nofollow noindex non-empty non-light-dark non-persisted non-string none noopener noreferrer normal noscript not not-object note now null number numeric object object-contain observe observer occurred of off og:description og:image og:image:alt og:image:height og:image:width og:title og:type og:url ol old older on once one only onto opacity-60 open open/close option or original other others out outline-none over overflow overflow-auto overflow-hidden overflow-x-auto overflow-y-auto overflow-y:auto overwrite own p p-0 p-hsp-lg p-hsp-md p-hsp-sm p-hsp-xl package package-owned packages padding page page-loading page-loading-overlay page-loading-spinner page-navigate-end page-title pages pages/. paint paint-and-read pan panel panels paren-balance-aware parent parse parsed pass passed passes path paths pattern pb-[50vh] pb-vsp-md pb-vsp-xl pb-vsp-xs per per-link permanently persisted pi pick picked picks picocolors pins pipelines pl-[1.25rem] pl-hsp-lg pl-hsp-sm pl-hsp-xl place placeholder placeholder:text-muted plain plural plus pnpm pointer-events-none pointercancel pointerdown pointermove pointerup polite polygon polyline populates port position position:fixed pr-[4px] pr-hsp-lg pr-hsp-md pr-hsp-sm pr-hsp-xl pre pre-lowercased preact preact/compat preact/hooks preact/jsx-runtime preconnect prefix preload pres preserving print produce produced produces production project project-root-relative properties property props prose provided proxy pt-[0.15rem] pt-[2px] pt-vsp-3xs pt-vsp-md pt-vsp-sm pt-vsp-xl pt-vsp-xs ptag- public purely px px-hsp-2xl px-hsp-2xs px-hsp-lg px-hsp-md px-hsp-sm px-hsp-xl px-hsp-xs py-0 py-[2px] py-[calc(var(--spacing-vsp-xs)+0.15rem)] py-hsp-2xs py-hsp-sm py-hsp-xs py-vsp-2xs py-vsp-3xs py-vsp-lg py-vsp-md py-vsp-sm py-vsp-xl py-vsp-xs q query question r radius raw re-encode/decode re-querying re-render re-renders re-run re-running re-selects reach reached reaches read reading ready real real-value received receives recorded recovers redefine ref- references refetch refreshes regenerate regenerates regex reinit reinits relative reload relying remove removed render rendered renders reorder repaint repeated repeating replaced replaces repopulate requires reserved resize resize-x resolve resolved resolves response restore restores result result-click results results-area retry return returns revision revisions rewrite right right- right-0 ro robots role root rotate-180 rotate-90 round round-trip rounded rounded-[0.75rem] rounded-bl-[0.25rem] rounded-bl-[1rem] rounded-br-[0.25rem] rounded-br-[1rem] rounded-full rounded-lg rounded-t-[1rem] rounds route router routes routes-src running runs runtime s safe safer same same-locale samp scale scanned schema-mismatch schema-missing scheme scored script script- script-eval script-evaluation script-injection scripts scroll scrollbar scrolled scrollend search search-index section section- see sel-bg sel-fg select select-none self self-start semibold sentinel separator serialised serialize server server-rendered set sets setting setup shadow-[0_1px_3px_color-mix(in_srgb,var(--color-fg)_8%,transparent)] shadow-lg shape share shared sharing shiki ship shipped ships short shortcut should show shown shrink-0 sidebar sidebar- sidebar-toggle-island sidebar-tree-island signal similarity single singular site-search site-tree-nav-island sitemap- sites size skill skills skipping skips slash slug sm:border sm:border-muted sm:flex-row sm:grid-cols-2 sm:h-auto sm:items-center sm:justify-between sm:max-h-[80vh] sm:max-w-[52rem] sm:mx-auto sm:my-[10vh] sm:rounded-lg small smooth snapshot snapshots so soft soft-nav solid some somehow source sources space-y-vsp-2xs spacing span spans spec specifier specifiers splitter square sr-only src stale start state status stay staying sticky still stop stored stray string strings strip stripe stroke-linecap stroke-linejoin stroke-width strong stronger style style-attribute styled styles stylesheet sub subagents subsequent success successful summary sup surfaces survives svg swap swapped swaps synchronous synchronously syntactically syntect t tab tab-item tab-panel tabindex table tablist tabpanel tabs tabs-container tabs-content tabs-nav tag tag- tag-item- tags tags:audit take tbody td temp-element template temporary temporary-element terminal terms test-results tested text text-accent text-bg text-body text-caption text-center text-chat-assistant-text text-chat-user-text text-code-fg text-danger text-decoration text-display text-fg text-heading text-info text-left text-micro text-muted text-muted/50 text-right text-small text-title text-warning text/plain textarea tfoot th that the thead their them theme theme-color theme-toggle theme/token then there these they this through throw tighten time tip title to toc toggle toggle-ai-chat toggle-design-token-panel toggles token tokens tolerates too toolbar top-0 top-[3.5rem] top-full top-level total touches tp tr tracked tracking-wider trade-off transition transition-[background,color,border-color] transition-[left,color] transition-colors transition-transform translate-x-0 translations transparent treats tree tree-child- tree-item- tree-top- trigger trigger:ai-chat trigger:design-token-panel triggers true truncate truncated try turn twitter:card twitter:creator twitter:description twitter:image twitter:site twitter:title two type typography u ul unavailable unchanged undefined under underline underlines understand unit-tested unknown unmaintained unobserve unreadable unrelated unreleased unset unsupported up uppercase usage use used user uses utf-8 utf8 utilities utility v v2 val value value-reader values var variable variant verbatim version version- version-menu version-switcher vertical via video viewport virtual:zudo-doc-chrome-bindings virtual:zudo-doc-route-context visible vitesse-dark vocabulary w w-1/2 w-[0.5rem] w-[0.625rem] w-[0.875rem] w-[1.125rem] w-[1.575rem] w-[1.5rem] w-[1.75rem] w-[14px] w-[16px] w-[16rem] w-[18px] w-[1em] w-[280px] w-[2rem] w-[320px] w-[90vw] w-[var(--zd-sidebar-w)] w-dvw w-full w-icon-lg w-icon-md w-icon-sm w-icon-xs want warning was watching wbr wbr- we website weight went were what when where whereas whether which while whitespace-nowrap whitespace-pre whole wide-gamut width will with without word working worktrees would wrap wrapper wrappers written wrong wrote xl:flex xl:hidden y-scrollbar yet you your z-dropdown z-local-1 z-modal z-modal-backdrop z-sidebar z-toolbar zd-content zd-desktop-sidebar-toggle zd-doc-content-band zd-enlarge-btn zd-enlarge-dialog zd-enlarge-dialog-close zd-enlargeable zd-html-preview-code zd-mermaid-dialog zd-mermaid-enlargeable zd-mermaid-tool-btn zd-mermaid-toolbar zd-mermaid-transform zd-mermaid-viewport zd-sidebar-content-wrapper zd-sidebar-open zfb zfb:after-swap zfb:before-preparation zod zoom zudo-doc-design-tokens/v1 zudo-doc-sidebar-visible zudo-doc-sidebar-width zudo-doc-theme zudo-doc-theme-bridge");
+@source inline("-link -mb-px -ml-hsp-sm -noscript -translate-x-full 2xl:w-[24px] [&::-webkit-details-marker]:hidden [&_a]:text-accent [&_a]:underline [&_nav]:mb-0 [data-admonition] [data-kbd-shortcut] [doc-history-meta] [doc-history] [doc-layout] [llms-txt] a a2 abbr about above absent absolute accent across activated active actual added admonition admonition- admonition-body admonition-title admonition/callout after after-breadcrumb after-content after-navigate after-sidebar after-title against agent agents ai-chat ai-chat-md ai-chat-trigger alert align-top all allow-same-origin allow-scripts alone already already-executed already-picked an anchor anchored and and/or animate-spin announce antialiased any application/json application/xml applies apply-css-vars approach are area arg aria-atomic aria-busy aria-controls aria-current aria-disabled aria-expanded aria-haspopup aria-hidden aria-label aria-live aria-orientation aria-pressed aria-selected aria-valuemax aria-valuemin aria-valuenow arm arms arrows article as asc aside aspect-[1200/630] aspect-square asset- assets assistant async at attach attribute attributes auto autogenerated available avoid await away b back backdrop:bg-bg/30 backdrop:bg-bg/80 backdrop:bg-overlay/60 backdrop:z-modal-backdrop background background-color backtick backticks baked banner bare base base64 based batch be because before below best between bg bg-[#fff] bg-accent bg-bg bg-chat-assistant-bg bg-chat-user-bg bg-code-bg bg-fg bg-info/10 bg-info/5 bg-muted bg-overlay/30 bg-surface bg-transparent bg-warning/10 bg-warning/5 bi bigint bin blank blanks blob block blockquote blocks blur body body-end-components body-end-scripts bold boolean bootstrap border border-accent border-b border-b-2 border-b-[5px] border-bg/30 border-collapse border-danger border-dashed border-fg border-info/30 border-l border-l-0 border-l-[3px] border-left-width border-muted border-none border-r border-radius border-solid border-t border-t-[2px] border-t-[3px] border-transparent border-warning/30 border-width border-y both bottom-vsp-xl box-border br brand breadcrumb:end breadcrumb:start break-words browser browsers btn bug build bundler but button buttons by bypassed byte-identical bytes cached call caller calls can cancellation cannot canonical canvas caption card card-grid carry cases cat-nav- catch category catppuccin-latte caught caution center center/contain ch chains change changed changes checkbox child chrome ci circle cite class class-less claude claude-agents claude-commands claude-md claude-skills cleaned clear clear-css-vars clearing click client client-router client-side clip clobbering close closed closing code code-block-sr-announce code-group code-group-panel col col-resize colgroup collision color color-scheme color-scheme-changed color-scheme-provider color-tweak colorization colors column comma command commands comment commit compare component component:github-link component:language-switcher component:search component:theme-toggle component:version-switcher compute computed concrete configuration configure configured confuse connect const construction consumer consumes container containers containing content content-admonition content-link content-type content-wrapper:end content-wrapper:start contents context controller controls converts copy corners correct correctly corrupt count covered covers cp crashes created cross-component crumb- cs css ctx cur current cursor cursor-not-allowed cursor-pointer custom danger dark data data-active data-admonition data-base data-close-search data-current-locale data-default-locale data-group-id data-header data-header-logo data-header-nav data-header-right data-kbd-shortcut data-language-switcher data-loading-index data-mermaid-enlarge-ready data-mermaid-rendered data-mermaid-src data-nav-active data-nav-item data-nav-item-dropdown data-nav-more data-nav-more-menu data-nav-more-toggle data-no-results data-open-search data-pan-active data-processed data-result-count-template data-search-count data-search-count-narrow data-search-dialog data-search-input data-search-placeholder data-search-results data-search-unavailable data-sidebar-hidden data-sidebar-resizer data-site-nav data-tab-btn data-tab-default data-tab-label data-tab-value data-tabs data-taglist-group data-testid data-theme data-theme/style data-trailing-slash data-variant data-version-banner data-version-latest data-version-menu data-version-rewire data-version-slug data-version-switcher data-version-toggle data-version-trigger-label data-zd-nosidebar data-zd-toc data-zfb-transition-persist dd decimal declare decoration decoration-muted default defaults del delegated dependency depth desc description design design-token-panel design-token-trigger desktop desktop-sidebar desktop-sidebar-toggle desktop-sidebar-toggle-island destructive detach detached details deterministic develop dfn diagram diagrams dialog dieser diff diff-line-added diff-line-content diff-line-empty diff-line-num diff-line-removed diff-row dir directly directories directory disabled disabled:opacity-50 disc display:none dist distinct div dl do doc doc-card- doc-content-band doc-history doc-history-generate doc-history-panel doc-history-trigger doc-page doc-pager doc-prose doc-title docs docs- docs-v- document document-level documented does double-registration drag draggable drop dropdown dropdown-child dropdown-parent dropdowns dt duration-150 duration-200 during dynamically e2e each ease-in-out edge eject ejected el element elements els else em embedded emit emitting empty empty/undefined en enable end enlarged entire entities entries entry error escape escaped even eventually every exactly excerpt excludes existing exists exit expected export extends factories failed fall fallback fallbacks falls false family fast feature feed fg fields fieldset figcaption figure file fill fills finally find fire fires first fixed fixed-width fixtures flag flash flat flex flex-1 flex-col flex-wrap flip flipping flips flush-left focus focus-visible:outline-2 focus-visible:outline-accent focus-visible:outline-offset-2 focus-visible:underline focus:border-accent focus:outline-none focus:underline font font-bold font-family font-medium font-mono font-semibold font-weight footer footer- for form found free fresh from frontmatter frontmatter-preview frozen fs-extra full fully function further g gap-[0.3em] gap-[clamp(1.5rem,3vw,4rem)] gap-hsp-2xs gap-hsp-md gap-hsp-sm gap-hsp-xl gap-hsp-xs gap-vsp-2xs gap-vsp-lg gap-vsp-md gap-vsp-xs gap-x-hsp-2xs gap-x-hsp-lg gap-x-hsp-md gap-x-hsp-sm gap-x-hsp-xs gap-y-vsp-2xs gap-y-vsp-lg gap-y-vsp-md gap-y-vsp-xs gaps gate generate generation genuine geometry get github github-link go got graph gray-matter grid grid-cols-1 grid-cols-2 group group-focus-visible:text-accent group-focus-visible:underline group-focus-within:block group-hover:bg-fg group-hover:block group-hover:text-accent group-hover:text-bg group-hover:underline group-open:rotate-90 guard h-[0.5rem] h-[0.625rem] h-[0.875rem] h-[1.125rem] h-[1.25rem] h-[1.575rem] h-[14px] h-[1em] h-[1lh] h-[2rem] h-[3.5rem] h-[3rem] h-[90vh] h-[calc(100%-3rem)] h-[calc(100vh-3.5rem)] h-dvh h-full h-icon-lg h-icon-md h-icon-sm h-icon-xs h1 h1s h2 h2s h3 h4 h5 h6 half hand hand-copied handle handled handler handlers has hash-link have head head-links head-scripts header header- header-call:end header-call:start heading heading-h2 heading-h3 heading-h4 headings height here hex hidden highlight highlighter history hit horizontal host hover:bg-[color-mix(in_srgb,var(--color-surface)_80%,var(--color-fg)_20%)] hover:bg-accent-hover hover:bg-accent/10 hover:bg-surface hover:border-accent hover:border-accent-hover hover:border-fg hover:text-accent hover:text-accent-hover hover:text-fg hover:underline hr href hrefs html i i18n/theme. i2 i3 i4 icon identical idle idx if iframe image image-enlarge image/png img implementation import important imports in inactive inbox includes index info inherit inherited initial initialised injected inline inline-block inline-flex inner input input-clear ins inset-0 inside install instance instanceof instead instructions intended intent into invalid inverse inversion invoke is issues it italic item item- items items-baseline items-center items-start its itself javascript justify-between justify-center justify-end justify-start katex kbd keep keeps kept keyboard keyboard-shortcut keydown keystroke keywords khroma label landing language-switcher last:border-b-0 later launch layout leading-relaxed leading-snug leading-tight leaf- leak leaves leaving left left-0 left:calc legend legitimate letter-spacing lg lg:block lg:border lg:border-fg lg:border-solid lg:flex lg:flex-col lg:flex-row lg:gap-hsp-xl lg:grid-cols-[repeat(auto-fit,minmax(12rem,1fr))] lg:h-[90vh] lg:hidden lg:justify-start lg:m-auto lg:max-h-[90vh] lg:max-w-[52.5rem] lg:ml-[var(--zd-sidebar-w)] lg:pt-vsp-2xl lg:px-hsp-2xl lg:py-vsp-2xl lg:text-left lg:w-[90vw] lg:w-[clamp(16rem,25%,22rem)] li li2 library light like likely line linger link link- links list-disc list-none listener literal literals lives llms llms-txt load local locale locales log longest-match look lostpointercapture lower luminance m m-0 m21 m6 main make malformed malicious maps mark marks matches matching math math-display math-inline max max-h-[80vh] max-h-[85vh] max-h-[90vh] max-h-full max-h-none max-w-[46rem] max-w-[85%] max-w-[85vw] max-w-[90vw] max-w-[clamp(50rem,75vw,90rem)] max-w-full max-w-none max-width may mb-0 mb-vsp-2xs mb-vsp-lg mb-vsp-md mb-vsp-sm mb-vsp-xl mb-vsp-xs measures measuring mechanism menu merged mermaid message messages meta meta-knob metadata migration min-h-[60vh] min-h-[calc(100vh-3.5rem)] min-h-screen min-w-0 min-w-[10rem] min-w-[8rem] mirror mirrors missing ml-auto ml-hsp-2xl ml-hsp-lg ml-hsp-sm ml-hsp-xl mod mode module mounted mouseenter mouseleave mr-hsp-sm mt-0 mt-vsp-2xl mt-vsp-2xs mt-vsp-3xs mt-vsp-lg mt-vsp-md mt-vsp-sm mt-vsp-xl must mutates mutation mutations mx-auto my-vsp-lg my-vsp-md name named native nav nav-active nav-card- nav/doc navigating navigation navigations near needs nested new newly-swapped next no no-enlarge no-op no-repeat no-underline node node:buffer node:fs node:fs/promises node:module node:path nodes nofollow noindex non-empty non-light-dark non-persisted non-string none noopener noreferrer normal noscript not not-object note now null number numeric object object-contain observe observer occurred of off og:description og:image og:image:alt og:image:height og:image:width og:title og:type og:url ol old older on once one only onto opacity-60 open open/close option or original other others out outline-none over overflow overflow-auto overflow-hidden overflow-x-auto overflow-y-auto overflow-y:auto overwrite own p p-0 p-hsp-lg p-hsp-md p-hsp-sm p-hsp-xl package package-owned packages padding page page-loading page-loading-overlay page-loading-spinner page-navigate-end page-title pages pages/. paint paint-and-read pan panel panels paren-balance-aware parent parse parsed pass passed passes path paths pattern pb-[50vh] pb-vsp-md pb-vsp-xl pb-vsp-xs per per-link permanently persisted pi pick picked picks picocolors pins pipelines pl-[1.25rem] pl-hsp-lg pl-hsp-sm pl-hsp-xl place placeholder placeholder:text-muted plain plural plus pnpm pointer-events-none pointercancel pointerdown pointermove pointerup polite polygon polyline populates port position position:fixed pr-[4px] pr-hsp-lg pr-hsp-md pr-hsp-sm pr-hsp-xl pre pre-lowercased preact preact/compat preact/hooks preact/jsx-runtime preconnect prefix preload pres preserving print produce produced produces production project project-root-relative properties property props prose provided proxy pt-[0.15rem] pt-[2px] pt-vsp-3xs pt-vsp-md pt-vsp-sm pt-vsp-xl pt-vsp-xs ptag- public purely px px-hsp-2xl px-hsp-2xs px-hsp-lg px-hsp-md px-hsp-sm px-hsp-xl px-hsp-xs py-0 py-[2px] py-[calc(var(--spacing-vsp-xs)+0.15rem)] py-hsp-2xs py-hsp-sm py-hsp-xs py-vsp-2xs py-vsp-3xs py-vsp-lg py-vsp-md py-vsp-sm py-vsp-xl py-vsp-xs q query question r radius raw re-encode/decode re-querying re-render re-renders re-run re-running re-selects reach reached reaches read reading ready real real-value received receives recorded recovers redefine ref- references refetch refreshes regenerate regenerates regex reinit reinits relative reload relying remove removed render rendered renders reorder repaint repeated repeating replaced replaces repopulate requires reserved resize resize-x resolve resolved resolves response restore restores result result-click results results-area retry return returns revision revisions rewrite right right- right-0 ro robots role root rotate-180 rotate-90 round round-trip rounded rounded-[0.75rem] rounded-bl-[0.25rem] rounded-bl-[1rem] rounded-br-[0.25rem] rounded-br-[1rem] rounded-full rounded-lg rounded-t-[1rem] rounds route router routes routes-src running runs runtime s safe safer same same-locale samp scale scanned schema-mismatch schema-missing scheme scored script script- script-eval script-evaluation script-injection scripts scroll scrollbar scrolled scrollend search search-index section section- see sel-bg sel-fg select select-none self self-start semibold sentinel separator serialised serialize server server-rendered set sets setting setup shadow-[0_1px_3px_color-mix(in_srgb,var(--color-fg)_8%,transparent)] shadow-lg shape share shared sharing shiki ship shipped ships short shortcut should show shown shrink-0 sidebar sidebar- sidebar-toggle-island sidebar-tree-island signal similarity single singular site-search site-tree-nav-island sitemap- sites size skill skills skipping skips slash slug sm:border sm:border-muted sm:flex-row sm:grid-cols-2 sm:h-auto sm:items-center sm:justify-between sm:max-h-[80vh] sm:max-w-[52rem] sm:mx-auto sm:my-[10vh] sm:rounded-lg small smooth snapshot snapshots so soft soft-nav solid some somehow source sources space-y-vsp-2xs spacing span spans spec specifier specifiers splitter square sr-only src stale start state status stay staying sticky still stop stored stray string strings strip stripe stroke-linecap stroke-linejoin stroke-width strong stronger style style-attribute styled styles stylesheet sub subagents subsequent success successful summary sup surfaces survives svg swap swapped swaps synchronous synchronously syntactically syntect t tab tab-item tab-panel tabindex table tablist tabpanel tabs tabs-container tabs-content tabs-nav tag tag- tag-item- tags tags:audit take tbody td temp-element template temporary temporary-element terminal terms test-results tested text text-accent text-bg text-body text-caption text-center text-chat-assistant-text text-chat-user-text text-code-fg text-danger text-decoration text-display text-fg text-heading text-info text-left text-micro text-muted text-muted/50 text-right text-small text-title text-warning text/plain textarea tfoot th that the thead their them theme theme-color theme-toggle theme/token then there these they this through throw tighten time tip title to toc toggle toggle-ai-chat toggle-design-token-panel toggles token tokens tolerates too toolbar top-0 top-[3.5rem] top-full top-level total touches tp tr tracked tracking-wider trade-off transition transition-[background,color,border-color] transition-[left,color] transition-colors transition-transform translate-x-0 translations transparent treats tree tree-child- tree-item- tree-top- trigger trigger:ai-chat trigger:design-token-panel triggers true truncate truncated try turn twitter:card twitter:creator twitter:description twitter:image twitter:site twitter:title two type typography u ul unavailable unchanged undefined under underline underlines understand unit-tested unknown unmaintained unobserve unreadable unrelated unreleased unset unsupported up uppercase usage use used user uses utf-8 utf8 utilities utility v v2 val value value-reader values var variable variant verbatim version version- version-menu version-switcher vertical via video viewport virtual:zudo-doc-chrome-bindings virtual:zudo-doc-route-context visible vitesse-dark vocabulary w w-1/2 w-[0.5rem] w-[0.625rem] w-[0.875rem] w-[1.125rem] w-[1.575rem] w-[1.5rem] w-[1.75rem] w-[14px] w-[16px] w-[16rem] w-[18px] w-[1em] w-[280px] w-[2rem] w-[320px] w-[90vw] w-[var(--zd-sidebar-w)] w-dvw w-full w-icon-lg w-icon-md w-icon-sm w-icon-xs want warning was watching wbr wbr- we website weight went were what when where whereas whether which while whitespace-nowrap whitespace-pre whole wide-gamut width will with without word working worktrees would wrap wrapper wrappers written wrong wrote xl:flex xl:hidden y-scrollbar yet you your z-dropdown z-local-1 z-modal z-modal-backdrop z-sidebar z-toolbar zd-content zd-desktop-sidebar-toggle zd-doc-content-band zd-enlarge-btn zd-enlarge-dialog zd-enlarge-dialog-close zd-enlargeable zd-html-preview-code zd-mermaid-dialog zd-mermaid-enlargeable zd-mermaid-tool-btn zd-mermaid-toolbar zd-mermaid-transform zd-mermaid-viewport zd-sidebar-content-wrapper zd-sidebar-open zfb zfb:after-swap zfb:before-preparation zod zoom zudo-doc-design-tokens/v1 zudo-doc-sidebar-visible zudo-doc-sidebar-width zudo-doc-theme zudo-doc-theme-bridge");

package/dist/settings.d.ts

@@ -301,6 +301,7 @@ export interface Settings {
     claudeResources: {
         claudeDir: string;
         projectRoot?: string;
+        scanRoot?: string;
     } | false;
     defaultLocaleOnlyPrefixes: string[];
     footer: FooterConfig | false;

package/eject/header/header.tsx

@@ -45,6 +45,8 @@ import {
   pathForMatch,
 } from "./nav-active.js";
 import { NAV_OVERFLOW_SCRIPT } from "./nav-overflow-script.js";
+import { LANGUAGE_SWITCHER_INIT_SCRIPT } from "../i18n-version/language-switcher.js";
+import { VERSION_SWITCHER_REWIRE_SCRIPT } from "../i18n-version/version-switcher.js";
 import type {
   HeaderNavItem,
   HeaderRightItem,
@@ -253,6 +255,7 @@ export function Header(props: HeaderProps): JSX.Element {
     headerRightItems,
     colorModeEnabled,
     hasLocales,
+    hasVersions,
     githubRepoUrl,
     githubLabel,
     urlHelpers,
@@ -279,8 +282,12 @@ export function Header(props: HeaderProps): JSX.Element {
       // AFTER_NAVIGATE_EVENT or URL derivation:
       //   - ThemeToggle: re-applies from localStorage on AFTER_NAVIGATE_EVENT
       //     (color-scheme-provider.tsx bootstrap script, #1546 verified (a))
-      //   - VersionSwitcher: VERSION_SWITCHER_INIT_SCRIPT re-wires toggle on
-      //     AFTER_NAVIGATE_EVENT (version-switcher.tsx:340, verified (a))
+      //   - VersionSwitcher: its menu hrefs, active row, and trigger label ARE
+      //     per-page (derived from currentSlug/currentVersion), so within a
+      //     same-locale persist window they WOULD go stale. VERSION_SWITCHER_INIT_SCRIPT
+      //     re-binds the dropdown toggle on AFTER_NAVIGATE_EVENT, and
+      //     VERSION_SWITCHER_REWIRE_SCRIPT recomputes the menu from
+      //     window.location on the same event (zudolab/zudo-doc#2553).
       //   - Search: <site-search> custom element re-registers on
       //     AFTER_NAVIGATE_EVENT (_search-widget-script.ts:184, verified (a))
       //   - SidebarToggle (mobile): closes on AFTER_NAVIGATE_EVENT
@@ -290,9 +297,12 @@ export function Header(props: HeaderProps): JSX.Element {
       //     Island re-hydrates with correct nodes on mount)
       //   - Header nav + aria-current: NAV_OVERFLOW_SCRIPT re-runs on
       //     AFTER_NAVIGATE_EVENT (nav-overflow-script.ts:198, verified (a))
-      //   - LanguageSwitcher: SSR'd locale links are locale-static within
-      //     a same-locale persist window — no per-page fields go stale
-      //     (verified (a) — locale does not change during same-locale nav)
+      //   - LanguageSwitcher: its target hrefs ARE per-page (the equivalent
+      //     page in each other locale), so within a same-locale persist window
+      //     they WOULD go stale — the locale is constant but the path is not.
+      //     LANGUAGE_SWITCHER_INIT_SCRIPT recomputes each anchor's href from
+      //     window.location on AFTER_NAVIGATE_EVENT, same as the controls above
+      //     (zudolab/zudo-doc#2551).
       // Omit persistKey to fall back to the old repaint-on-every-swap path.
       data-zfb-transition-persist={persistKey}
     >
@@ -365,6 +375,24 @@ export function Header(props: HeaderProps): JSX.Element {
       </div>
 
       <script dangerouslySetInnerHTML={{ __html: NAV_OVERFLOW_SCRIPT }} />
+      {hasLocales ? (
+        // Keeps the persisted header's language-switcher hrefs pointing at the
+        // current page's equivalent in each other locale across same-locale SPA
+        // navigation (#2551). Registers a document-level AFTER_NAVIGATE_EVENT
+        // listener once; idempotent across re-execution.
+        <script
+          dangerouslySetInnerHTML={{ __html: LANGUAGE_SWITCHER_INIT_SCRIPT }}
+        />
+      ) : null}
+      {hasVersions ? (
+        // Keeps the persisted header's version-switcher menu hrefs / active row /
+        // trigger label tracking the current page across same-locale SPA
+        // navigation (#2553). Registers a document-level AFTER_NAVIGATE_EVENT
+        // listener once; idempotent across re-execution.
+        <script
+          dangerouslySetInnerHTML={{ __html: VERSION_SWITCHER_REWIRE_SCRIPT }}
+        />
+      ) : null}
     </header>
   );
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@takazudo/zudo-doc",
-  "version": "2.4.0",
+  "version": "2.5.0",
   "type": "module",
   "description": "zudo-doc framework primitives layer that sits on top of zfb's engine — sidebar, theme, TOC, breadcrumb, layouts, head injection, View Transitions, SSR-skip wrappers (per ADR-003).",
   "license": "MIT",
@@ -540,8 +540,8 @@
   ],
   "peerDependencies": {
     "preact": "^10.29.1",
-    "@takazudo/zfb": "^0.1.0-next.75",
-    "@takazudo/zfb-runtime": "^0.1.0-next.75",
+    "@takazudo/zfb": "^0.1.0-next.76",
+    "@takazudo/zfb-runtime": "^0.1.0-next.76",
     "@takazudo/zudo-doc-history-server": "^2.2.1",
     "@takazudo/zdtp": "^0.4.2",
     "shiki": "^4.0.2",
@@ -584,9 +584,9 @@
     "typescript": "^5.0.0",
     "vitest": "^4.1.0",
     "zod": "^4.3.6",
-    "@takazudo/zfb": "0.1.0-next.75",
-    "@takazudo/zfb-runtime": "0.1.0-next.75",
-    "@takazudo/zudo-doc-history-server": "2.4.0"
+    "@takazudo/zfb": "0.1.0-next.76",
+    "@takazudo/zfb-runtime": "0.1.0-next.76",
+    "@takazudo/zudo-doc-history-server": "2.5.0"
   },
   "scripts": {
     "build": "tsup && tsc -p tsconfig.build.json",