@takazudo/zudo-doc 4.4.13 → 5.0.0

package/dist/doc-page-renderer/index.js

@@ -3,7 +3,11 @@ import { createDocPageShell } from "../doc-page-shell/index.js";
 import { createDocContentHeader } from "../doc-content-header/index.js";
 import { createDocMetainfoArea } from "../doc-metainfo-area/index.js";
 import { createDocHistoryArea } from "../doc-history-area/index.js";
-import { deriveMdxComponents, deriveInlineVersionSwitcher } from "../chrome/derive.js";
+import {
+  deriveMdxComponents,
+  deriveInlineVersionSwitcher,
+  deriveGetUnavailableVersions
+} from "../chrome/derive.js";
 import { assertChromeContext } from "../chrome/assert-chrome-context.js";
 function createRenderDocPage(ctx) {
   assertChromeContext(ctx, "createRenderDocPage");
@@ -14,8 +18,10 @@ function createRenderDocPage(ctx) {
   const toRouteSlug = ctx.toRouteSlug;
   const createMdxComponents = deriveMdxComponents(ctx).createMdxComponentsBound;
   const t = ctx.t;
+  const getUnavailableVersions = deriveGetUnavailableVersions(ctx);
   const buildInlineVersionSwitcher = deriveInlineVersionSwitcher(
-    ctx
+    ctx,
+    getUnavailableVersions
   );
   const DocPageShell = createDocPageShell(ctx);
   const DocContentHeader = createDocContentHeader(
@@ -29,7 +35,7 @@ function createRenderDocPage(ctx) {
     const slug = props.kind === "autoIndex" ? props.autoIndex.slug : props.entry.data.slug ?? toRouteSlug(props.entry.slug);
     const title = props.kind === "autoIndex" ? props.autoIndex.label : props.entry.data.title;
     const description = props.kind === "autoIndex" ? props.autoIndex.description : props.entry.data.description;
-    const components = createMdxComponents(locale);
+    const components = createMdxComponents(locale, version?.slug);
     const autoIndexChildren = props.kind === "autoIndex" ? version ? props.autoIndex.children.filter((c) => c.hasPage || c.children.length > 0) : props.autoIndex.children.filter((c) => c.hasPage || c.children.length > 0).map((c) => ({
       ...c,
       href: c.href ?? docsUrl(c.slug, locale)
@@ -71,6 +77,7 @@ function createRenderDocPage(ctx) {
         currentPath,
         currentVersion: version?.slug,
         versionSwitcher: buildInlineVersionSwitcher(slug, locale, version?.slug),
+        unavailableVersions: getUnavailableVersions(slug, locale),
         versionBanner: versionBannerType,
         versionBannerLatestUrl,
         versionBannerLabels,

package/dist/doc-page-shell/index.d.ts

@@ -60,6 +60,19 @@ export interface DocPageShellProps {
     currentVersion?: string;
     /** Inline version switcher VNode for the breadcrumb right-slot. */
     versionSwitcher: ComponentChildren;
+    /**
+     * This page's unavailable-version slugs, straight from
+     * `getUnavailableVersions(slug, locale)` (`../version-availability`) —
+     * NOT re-derived here. Serialized onto `<article>` via
+     * `serializeUnavailableVersions` so a same-locale SPA navigation rewire
+     * script (#3244) can read the per-page availability set after the
+     * persisted header's own SSR attributes go stale. `undefined` (no
+     * availability data — e.g. versioning not configured) renders NO
+     * attribute at all; an empty set renders the attribute with an empty
+     * value. See `../version-availability/index.ts` for the full
+     * absent/empty/populated contract.
+     */
+    unavailableVersions?: ReadonlySet<string>;
     /** Version banner type ("unmaintained" | "unreleased") or undefined on latest. */
     versionBanner?: "unmaintained" | "unreleased";
     /** URL of the latest equivalent page for the version banner link. */

package/dist/doc-page-shell/index.js

@@ -7,6 +7,11 @@ import {
   createSidebarPrepaint,
   createSidebarVisibilityPrepaint
 } from "../sidebar-prepaint/index.js";
+import {
+  createTocPrepaint,
+  createTocVisibilityPrepaint
+} from "../toc-prepaint/index.js";
+import { serializeUnavailableVersions } from "../version-availability/index.js";
 import { createHeadWithDefaults } from "../head-with-defaults/index.js";
 import { resolveThemePackSsrSlug } from "../theme/theme-pack-provider.js";
 import { createDocBodyEnd } from "../doc-body-end/index.js";
@@ -36,6 +41,13 @@ function createDocPageShell(ctx) {
   const SidebarVisibilityPrepaint = createSidebarVisibilityPrepaint({
     sidebarToggle: sidebarToggleEnabled
   });
+  const tocToggleEnabled = Boolean(
+    ctx.settings.tocToggle
+  );
+  const TocPrepaint = createTocPrepaint({ tocToggle: tocToggleEnabled });
+  const TocVisibilityPrepaint = createTocVisibilityPrepaint({
+    tocToggle: tocToggleEnabled
+  });
   const DocBodyEnd = createDocBodyEnd(ctx);
   const dataThemePack = resolveThemePackSsrSlug(
     ctx.themePackRegistry,
@@ -60,6 +72,7 @@ function createDocPageShell(ctx) {
       currentPath,
       currentVersion,
       versionSwitcher,
+      unavailableVersions,
       versionBanner,
       versionBannerLatestUrl,
       versionBannerLabels,
@@ -72,6 +85,7 @@ function createDocPageShell(ctx) {
     } = props;
     const tocTitle = getTocTitle(locale);
     const shouldRenderToc = !hideToc && headings.length > 0;
+    const shouldRenderDefaultToc = shouldRenderToc && !customTocIsPresent;
     const tocOverride = shouldRenderToc ? customTocIsPresent ? /* @__PURE__ */ jsx(Toc, { headings, title: tocTitle }) : (
       // The zfb <Island> wrapper renders a bare <div> with no class, so
       // below xl (where <Toc> itself is `hidden xl:flex`) it would remain
@@ -80,7 +94,22 @@ function createDocPageShell(ctx) {
       // left at mobile widths. Hide the flex child itself below xl so it
       // contributes no gap; the bare-nav override branch above is already
       // self-hiding via <Toc>'s own `hidden xl:flex`. (#3082)
-      /* @__PURE__ */ jsx("div", { class: "hidden xl:block", children: Island({
+      //
+      // Load-bearing for the TOC's sticky scroll-follow: this wrapper must
+      // be `xl:flex`, never `xl:block`.  safelist-ok: `xl:block` names the rejected alternative in prose; only `xl:flex` below is emitted
+      // A sticky box can only travel within its parent's box, and the
+      // classless <Island> div sits between this wrapper and <Toc>'s
+      // sticky <nav>. As a block container that div is auto-height, so it
+      // collapses to exactly the nav's height and the nav has zero travel
+      // — it scrolls away with the page instead of pinning. Flex stretches
+      // the Island div to full content-band height (default
+      // `align-items: stretch`), restoring the travel range. (#3202)
+      //
+      // `zd-toc-col` is the stable hook class for the desktop TOC-toggle
+      // CSS (features.css "Desktop TOC toggle" block, #3254) — only the
+      // default-TOC wrapper carries it; the custom-Toc branch above stays
+      // bare and unaffected by the toggle feature.
+      /* @__PURE__ */ jsx("div", { class: "zd-toc-col hidden xl:flex", children: Island({
         when: "load",
         children: /* @__PURE__ */ jsx(Toc, { headings, title: tocTitle })
       }) })
@@ -96,7 +125,8 @@ function createDocPageShell(ctx) {
         description: settings.metaTags.description ? description : void 0,
         head: /* @__PURE__ */ jsxs(Fragment, { children: [
           /* @__PURE__ */ jsx(HeadWithDefaults, { title, description, canonical }),
-          /* @__PURE__ */ jsx(SidebarVisibilityPrepaint, { hideSidebar })
+          /* @__PURE__ */ jsx(SidebarVisibilityPrepaint, { hideSidebar }),
+          /* @__PURE__ */ jsx(TocVisibilityPrepaint, { shouldRenderDefaultToc })
         ] }),
         lang: locale,
         dataThemePack,
@@ -133,10 +163,14 @@ function createDocPageShell(ctx) {
         ),
         tocOverride,
         mobileTocOverride,
-        afterSidebar: /* @__PURE__ */ jsx(SidebarPrepaint, { hideSidebar }),
+        afterSidebar: /* @__PURE__ */ jsxs(Fragment, { children: [
+          /* @__PURE__ */ jsx(SidebarPrepaint, { hideSidebar }),
+          /* @__PURE__ */ jsx(TocPrepaint, { shouldRenderDefaultToc })
+        ] }),
         footerOverride: /* @__PURE__ */ jsx(FooterWithDefaults, { lang: locale }),
         bodyEndComponents: /* @__PURE__ */ jsx(DocBodyEnd, {}),
         enableClientRouter: settings.dynamicPageTransition,
+        articleAttrs: serializeUnavailableVersions(unavailableVersions),
         children: kind === "autoIndex" ? (
           /* Auto-index page: category without an index.mdx.
              Fragment (not <div>) so children become direct children of

package/dist/doclayout/doc-layout.d.ts

@@ -89,6 +89,20 @@ export interface DocLayoutProps extends DocLayoutHtmlAttrs {
      * doc-history feature.
      */
     afterContent?: ComponentChildren;
+    /**
+     * Raw `data-*` attributes spread onto the `<article>` element. This shell
+     * stays version/i18n-agnostic on purpose (see the module header), so it
+     * has no idea what any given key means — it is a generic passthrough, not
+     * a versioning-aware prop. `<DocPageShell>` (one level up) is the actual
+     * owner of the one entry currently threaded through here: the per-page
+     * version-availability payload documented in
+     * `../version-availability/index.ts` (`UNAVAILABLE_VERSIONS_ATTR`). Placed
+     * on `<article>` rather than a new wrapper element because `<article>` is
+     * always present, sits inside `<main>` (swapped content — see the SPA
+     * persist note on the sidebar `<aside>` above), and needs no DOM node of
+     * its own that could shift the `.zd-content` flow-space rhythm.
+     */
+    articleAttrs?: Record<string, string>;
     /** Optional desktop TOC rendered alongside `<main>` on wide screens. */
     toc?: ComponentChildren;
     /** Hide the TOC (both desktop and mobile) regardless of slot value. */

package/dist/doclayout/doc-layout.js

@@ -21,6 +21,7 @@ function DocLayout(props) {
     mobileToc,
     main,
     afterContent,
+    articleAttrs,
     toc,
     hideToc = false,
     contentWide = false,
@@ -54,7 +55,8 @@ function DocLayout(props) {
           "data-sidebar-hidden",
           "data-theme",
           "data-theme-pack",
-          "style"
+          "style",
+          "data-toc-hidden"
         ]
       }) : null,
       head
@@ -88,7 +90,7 @@ function DocLayout(props) {
                     breadcrumb,
                     afterBreadcrumb,
                     !hideToc && mobileToc,
-                    /* @__PURE__ */ jsx("article", { class: "zd-content max-w-none", children: main }),
+                    /* @__PURE__ */ jsx("article", { class: "zd-content max-w-none", ...articleAttrs, children: main }),
                     afterContent
                   ] }),
                   showToc && toc

package/dist/features.css

@@ -372,6 +372,66 @@ html[data-sidebar-hidden] .zd-doc-content-band[data-zd-wide] {
  * before paint, so the sidebar never wipes-and-restores and no geometry
  * transition fires mid-swap. Retires the #2198 workaround (zudolab/zudo-doc#2200). */
 
+/* ========================================
+ * Desktop TOC toggle — 1:1 mirror of "Desktop sidebar toggle" above (epic
+ * #3252, #3254). Breakpoint is xl/1280px, NOT the sidebar's lg/1024px.
+ *
+ * `data-toc-hidden` persists across SPA navigation (doc-layout.tsx
+ * preserveHtmlAttrs), so EVERY hidden-state rule below is scoped to the
+ * default-TOC path (`.zd-toc-col` descendants / `:has(> .zd-toc-col)`) — an
+ * unscoped rule would collapse/squish a *custom* Toc reached after hiding the
+ * default TOC on another page.
+ * ======================================== */
+
+@media (min-width: 1280px) {
+  .zd-toc-col {
+    width: var(--zdc-toc-width, 280px); /* explicit — auto→0 does not interpolate */
+    overflow: clip; /* NOT hidden: hidden creates a scroll container and breaks the nav's sticky */
+    transition: width var(--zd-transition-slow) ease-in-out;
+  }
+
+  html[data-toc-hidden] .zd-toc-col {
+    width: 0;
+  }
+
+  /* :has guard keeps the gap intact on custom-Toc pages (wrapper is a direct
+   * band child). Without :has support the gap simply stays — cosmetic
+   * degradation only. Alternative if :has ever becomes a concern: a band
+   * marker attribute. */
+  html[data-toc-hidden] .zd-doc-content-band:has(> .zd-toc-col) {
+    gap: 0;
+  }
+
+  /* COMBINED list — a bare `transition: gap` here would override and drop the
+   * max-width transition declared in the sidebar's 1024px block (last wins at
+   * xl, same property on the same selector). No band max-width rule is added
+   * here (expand-main policy): `main` is already `flex-1 min-w-0` and absorbs
+   * the freed width by itself; both-hidden composes with the existing
+   * `html[data-sidebar-hidden] .zd-doc-content-band { max-width: 80rem }` cap. */
+  .zd-doc-content-band {
+    transition:
+      max-width var(--zd-transition-slow) ease-in-out,
+      gap var(--zd-transition-slow) ease-in-out;
+  }
+
+  .zd-toc-col nav[data-zd-toc] {
+    transition:
+      opacity var(--zd-transition-slow) ease-in-out,
+      transform var(--zd-transition-slow) ease-in-out,
+      visibility var(--zd-transition-slow);
+  }
+
+  html[data-toc-hidden] .zd-toc-col nav[data-zd-toc] {
+    opacity: 0;
+    transform: translateX(1.5rem);
+    visibility: hidden; /* a11y: clipped links must not be focusable */
+  }
+
+  .zd-desktop-toc-toggle {
+    right: 0; /* constant — pins to the viewport edge; no tracking var needed */
+  }
+}
+
 /* ========================================
  * Page transition animations (view-transition chrome)
  * ======================================== */
@@ -403,19 +463,21 @@ html[data-sidebar-hidden] .zd-doc-content-band[data-zd-wide] {
  * transitions via document.startViewTransition on each navigation.
  *
  * Chrome extraction via view-transition-name (Strategy B+, zudolab/zudo-doc#1558):
- * <header>, <aside id="desktop-sidebar">, <footer>, and the desktop-sidebar-toggle
- * button each carry a data-zfb-transition-persist attribute whose value is keyed
- * by locale and nav-section. The four attribute selectors below assign a stable
+ * <header>, <aside id="desktop-sidebar">, <footer>, the desktop-sidebar-toggle
+ * button, and (since #3254) the desktop-toc-toggle button each carry a
+ * data-zfb-transition-persist attribute whose value is keyed by locale and
+ * nav-section. The five attribute selectors below assign a stable
  * view-transition-name based on the attribute value prefix, extracting those
  * elements from the root snapshot into their own named layers:
  *   - header-{lang}          → zfb-header
  *   - sidebar-{locale}-…     → zfb-sidebar
  *   - footer-{lang}          → zfb-footer
  *   - desktop-sidebar-toggle → zfb-sidebar-toggle
+ *   - desktop-toc-toggle     → zfb-toc-toggle
  *
  * Once extracted, the root cross-fade animates only non-chrome content (main,
- * article, TOC, etc.). The twelve ::view-transition-{old,new,group}(<name>)
- * rules disable animation for all four chrome layers. The group pseudo must be
+ * article, TOC, etc.). The ::view-transition-{old,new,group}(<name>) rules
+ * disable animation for all five chrome layers. The group pseudo must be
  * neutralised too — even when old/new are static the group container can still
  * produce a geometry-morph animation when snapshot size/position differs.
  *
@@ -434,8 +496,11 @@ html[data-sidebar-hidden] .zd-doc-content-band[data-zd-wide] {
 [data-zfb-transition-persist^="sidebar-"]              { view-transition-name: zfb-sidebar; }
 [data-zfb-transition-persist^="footer-"]               { view-transition-name: zfb-footer; }
 [data-zfb-transition-persist="desktop-sidebar-toggle"] { view-transition-name: zfb-sidebar-toggle; }
+[data-zfb-transition-persist="desktop-toc-toggle"]     { view-transition-name: zfb-toc-toggle; }
 
-/* Disable animation for all four chrome layers (old, new, and group) */
+/* Disable animation for all four chrome layers (old, new, and group), plus
+ * the desktop-toc-toggle button (#3254 — mirrors desktop-sidebar-toggle so
+ * it doesn't animate on SPA swaps). */
 ::view-transition-old(zfb-header),
 ::view-transition-new(zfb-header),
 ::view-transition-group(zfb-header),
@@ -447,21 +512,26 @@ html[data-sidebar-hidden] .zd-doc-content-band[data-zd-wide] {
 ::view-transition-group(zfb-footer),
 ::view-transition-old(zfb-sidebar-toggle),
 ::view-transition-new(zfb-sidebar-toggle),
-::view-transition-group(zfb-sidebar-toggle) { animation: none; }
+::view-transition-group(zfb-sidebar-toggle),
+::view-transition-old(zfb-toc-toggle),
+::view-transition-new(zfb-toc-toggle),
+::view-transition-group(zfb-toc-toggle) { animation: none; }
 
 /* Entry/exit: chrome element present on one side only (#2072).
  * Exit — lone old snapshot fades out with the content cross-fade. */
 ::view-transition-old(zfb-header):only-child,
 ::view-transition-old(zfb-sidebar):only-child,
 ::view-transition-old(zfb-footer):only-child,
-::view-transition-old(zfb-sidebar-toggle):only-child {
+::view-transition-old(zfb-sidebar-toggle):only-child,
+::view-transition-old(zfb-toc-toggle):only-child {
   animation: var(--default-transition-duration) ease-in both contentFadeOut;
 }
 /* Entry — lone new snapshot fades in with the content cross-fade. */
 ::view-transition-new(zfb-header):only-child,
 ::view-transition-new(zfb-sidebar):only-child,
 ::view-transition-new(zfb-footer):only-child,
-::view-transition-new(zfb-sidebar-toggle):only-child {
+::view-transition-new(zfb-sidebar-toggle):only-child,
+::view-transition-new(zfb-toc-toggle):only-child {
   animation: var(--zd-transition-slower) ease-out both contentFadeIn;
 }
 
@@ -492,10 +562,12 @@ html[data-sidebar-hidden] .zd-doc-content-band[data-zd-wide] {
   ::view-transition-old(zfb-sidebar):only-child,
   ::view-transition-old(zfb-footer):only-child,
   ::view-transition-old(zfb-sidebar-toggle):only-child,
+  ::view-transition-old(zfb-toc-toggle):only-child,
   ::view-transition-new(zfb-header):only-child,
   ::view-transition-new(zfb-sidebar):only-child,
   ::view-transition-new(zfb-footer):only-child,
-  ::view-transition-new(zfb-sidebar-toggle):only-child {
+  ::view-transition-new(zfb-sidebar-toggle):only-child,
+  ::view-transition-new(zfb-toc-toggle):only-child {
     animation: none;
   }
 }

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

@@ -65,6 +65,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") }),

package/dist/header/header.d.ts

@@ -10,7 +10,7 @@ import type { HeaderNavItem, HeaderRightComponentRegistry, HeaderRightItem, Loca
 export interface HeaderUrlHelpers {
     withBase(path: string): string;
     stripBase(path: string): string;
-    navHref(path: string, lang?: Locale, currentVersion?: string): string;
+    navHref(path: string, lang?: Locale, currentVersion?: string, versioned?: boolean): string;
 }
 /**
  * Boundary helpers for locale-aware behaviour the host injects into

package/dist/header/header.js

@@ -166,7 +166,7 @@ function SidebarSlotFallback({
 }
 function renderNavItem(item, activeNavPath, activeCategory, lang, currentVersion, urlHelpers, i18n) {
   const isActive = isNavItemActiveByCategory(item, activeCategory) || isNavItemActive(item, activeNavPath);
-  const href = urlHelpers.navHref(item.path, lang, currentVersion);
+  const href = urlHelpers.navHref(item.path, lang, currentVersion, item.versioned);
   const label = item.labelKey ? i18n.t(item.labelKey, lang) : item.label;
   if (item.children && item.children.length > 0) {
     return /* @__PURE__ */ jsxs(
@@ -215,7 +215,7 @@ function renderNavItem(item, activeNavPath, activeCategory, lang, currentVersion
             }
           ),
           /* @__PURE__ */ jsx("div", { class: "absolute left-0 top-full z-dropdown hidden group-hover:block group-focus-within:block pt-vsp-3xs", children: /* @__PURE__ */ jsx("div", { class: "min-w-[10rem] border border-muted rounded bg-surface shadow-lg py-vsp-3xs", children: item.children.map((child) => {
-            const childHref = urlHelpers.navHref(child.path, lang, currentVersion);
+            const childHref = urlHelpers.navHref(child.path, lang, currentVersion, child.versioned);
             const childLabel = child.labelKey ? i18n.t(child.labelKey, lang) : child.label;
             const childActive = isNavItemActiveByCategory(child, activeCategory) || activeNavPath === child.path;
             return /* @__PURE__ */ jsx(

package/dist/header/types.d.ts

@@ -11,6 +11,13 @@ export interface HeaderNavChildItem {
     labelKey?: string;
     path: string;
     categoryMatch?: string;
+    /**
+     * Whether links built from this item's `path` carry the active `/v/{version}`
+     * prefix. `false` targets a route that has no versioned counterpart, so its
+     * href must stay unversioned even when rendered under an active version.
+     * Default `true`.
+     */
+    versioned?: boolean;
 }
 export interface HeaderNavItem extends HeaderNavChildItem {
     children?: HeaderNavChildItem[];

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

@@ -32,10 +32,12 @@ export interface HeaderWithDefaultsSettings {
         labelKey?: string;
         path: string;
         categoryMatch?: string;
+        versioned?: boolean;
         children?: Array<{
             label: string;
             labelKey?: string;
             path: string;
+            versioned?: boolean;
         }>;
     }>;
     headerRightItems?: unknown[];

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

@@ -9,7 +9,11 @@ import { ThemeToggle } from "../theme-toggle/index.js";
 import { SidebarToggle } from "../sidebar-toggle-island/index.js";
 import { buildGitHubRepoUrl as buildGitHubRepoUrlBase } from "../github-helpers/index.js";
 import { assertChromeContext } from "../chrome/assert-chrome-context.js";
-import { deriveNavDataPrep, deriveSearchWidgetSlot } from "../chrome/derive.js";
+import {
+  deriveGetUnavailableVersions,
+  deriveNavDataPrep,
+  deriveSearchWidgetSlot
+} from "../chrome/derive.js";
 function createHeaderWithDefaults(ctx) {
   assertChromeContext(ctx, "createHeaderWithDefaults");
   const settings = ctx.settings;
@@ -24,6 +28,7 @@ function createHeaderWithDefaults(ctx) {
   const { buildRootMenuItems, buildLocaleLinksForNav, buildSidebarNodes, getThemeDefaultMode } = deriveNavDataPrep(ctx);
   const buildGitHubRepoUrl = () => buildGitHubRepoUrlBase(ctx.settings.githubUrl);
   const SearchWidget = deriveSearchWidgetSlot(ctx);
+  const getUnavailableVersions = deriveGetUnavailableVersions(ctx);
   function HeaderWithDefaults(props) {
     const {
       lang: langProp = defaultLocale,
@@ -85,6 +90,7 @@ function createHeaderWithDefaults(ctx) {
         unavailable: t("version.switcher.unavailable", lang),
         allVersions: t("version.switcher.allVersions", lang)
       };
+      const unavailableVersions = getUnavailableVersions(currentSlug, lang);
       versionSwitcher = /* @__PURE__ */ jsx(
         VersionSwitcher,
         {
@@ -96,6 +102,7 @@ function createHeaderWithDefaults(ctx) {
           latestUrl,
           versionsPageUrl,
           versionUrls,
+          unavailableVersions,
           labels,
           idSuffix: "header",
           rewireConfig: {
@@ -158,7 +165,7 @@ function createHeaderWithDefaults(ctx) {
         urlHelpers: {
           withBase,
           stripBase,
-          navHref: (path, l, v) => navHref(path, l, v)
+          navHref: (path, l, v, versioned) => navHref(path, l, v, versioned)
         },
         i18n: {
           defaultLocale,

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

@@ -169,6 +169,42 @@ export declare const VERSION_SWITCHER_INIT_SCRIPT: string;
  * {@link VersionSwitcherRewireConfig} is passed), so the inline breadcrumb
  * switcher — re-rendered fresh on every swap — is left alone.
  *
+ * Since #3244, `rewire()` also recomputes each version entry's
+ * enabled/disabled state from the per-page availability payload #3243 emits
+ * onto the swapped `<article>` (`UNAVAILABLE_VERSIONS_ATTR`, imported here
+ * as `ATTR` — see `version-availability/index.ts` for the three-state
+ * contract). The persisted header would otherwise keep showing whichever
+ * entries were disabled/enabled on the PREVIOUS page after a same-locale SPA
+ * navigation — the exact bug epic #3242 exists to fix.
+ *
+ * The three-state contract is preserved faithfully here (fixed after a P2
+ * codex review finding on the original #3244 landing, which collapsed ABSENT
+ * into EMPTY and re-enabled every entry — turning SSR-correct disabled links
+ * into live 404s whenever a page renders through `createDocPageShell` without
+ * an availability payload):
+ *   - attribute ABSENT (`hasAvailabilityData` false) → no availability data
+ *     for the destination page. `setDisabled` is never called for any entry;
+ *     the SSR-rendered disabled/enabled state is left exactly as-is. Only the
+ *     genuinely path-derived bits (href, active state on entries that are
+ *     NOT currently disabled) are recomputed.
+ *   - attribute present, value `""` → empty unavailable set, i.e. "everything
+ *     available" — `setDisabled(a, false, …)` runs for every entry, matching
+ *     the SSR component's own `!unavailableVersions || !unavailableVersions.has(slug)`
+ *     fallback (`version-switcher.tsx`'s `isAvailable` check).
+ *   - attribute present, `"a,b"` → those slugs disabled, the rest enabled.
+ *
+ * `setDisabled` and the `setActive` guard together transition ALL FIVE
+ * SSR-divergent properties in both directions (`aria-disabled`, `tabindex`,
+ * `title`, the disjoint class sets, `aria-current`) — see the case table in
+ * `__tests__/version-switcher.test.tsx` that pins this against the real SSR
+ * branches. `setActive` runs strictly AFTER `setDisabled` re-enables an
+ * entry, so a newly-available active entry gets `aria-current="page"`
+ * restored instead of silently staying without it. In the ABSENT branch,
+ * where `setDisabled` never runs, `setActive` instead reads the anchor's
+ * OWN current `aria-disabled` attribute directly (the only source of truth
+ * left, since availability isn't being recomputed) and skips already-disabled
+ * entries the same way.
+ *
  * `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.

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 { UNAVAILABLE_VERSIONS_ATTR } from "../version-availability/index.js";
 function computeVersionSwitcherState(pathname, config, versionSlugs) {
   const normalizedBase = config.base;
   const defaultLocale = config.defaultLocale;
@@ -105,7 +106,8 @@ function VersionSwitcher(props) {
     "data-base": rewireConfig.base,
     "data-default-locale": rewireConfig.defaultLocale,
     "data-trailing-slash": String(rewireConfig.trailingSlash),
-    "data-current-locale": rewireConfig.currentLocale
+    "data-current-locale": rewireConfig.currentLocale,
+    "data-unavailable-label": labels.unavailable
   } : {};
   return /* @__PURE__ */ jsxs("div", { class: "version-switcher relative", "data-version-switcher": true, ...rewireAttrs, children: [
     /* @__PURE__ */ jsxs(
@@ -232,6 +234,7 @@ const VERSION_SWITCHER_REWIRE_SCRIPT = `(function(){
 var FLAG="__zdVersionSwitcherRewire";
 if(window[FLAG])return;
 window[FLAG]=true;
+var ATTR=${JSON.stringify(UNAVAILABLE_VERSIONS_ATTR)};
 var computeVersionSwitcherState=${computeVersionSwitcherState.toString()};
 function setActive(a,active){
 a.classList.toggle("font-bold",active);
@@ -239,11 +242,34 @@ 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 setDisabled(a,disabled,unavailableLabel){
+a.classList.toggle("hover:bg-accent/10",!disabled);
+a.classList.toggle("hover:underline",!disabled);
+a.classList.toggle("focus-visible:underline",!disabled);
+a.classList.toggle("text-muted/50",disabled);
+a.classList.toggle("cursor-not-allowed",disabled);
+a.classList.toggle("pointer-events-none",disabled);
+if(disabled){
+a.setAttribute("aria-disabled","true");
+a.setAttribute("tabindex","-1");
+a.setAttribute("title",unavailableLabel);
+a.classList.remove("font-bold","text-accent","text-fg");
+a.removeAttribute("aria-current");
+}else{
+a.removeAttribute("aria-disabled");
+a.removeAttribute("tabindex");
+a.removeAttribute("title");
+}
+}
 function rewire(){
+var articleEl=document.querySelector("["+ATTR+"]");
+var hasAvailabilityData=articleEl!==null;
+var unavailableSlugs=hasAvailabilityData?(articleEl.getAttribute(ATTR)||"").split(",").filter(Boolean):[];
 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 unavailableLabel=c.getAttribute("data-unavailable-label")||"";
 var versionAnchors=c.querySelectorAll("[data-version-slug]");
 var slugs=[];
 for(var j=0;j<versionAnchors.length;j++){
@@ -262,7 +288,14 @@ 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);
+if(hasAvailabilityData){
+var disabled=unavailableSlugs.indexOf(slug)!==-1;
+setDisabled(a,disabled,unavailableLabel);
+if(!disabled)setActive(a,state.activeVersion===slug);
+}else{
+var alreadyDisabled=a.getAttribute("aria-disabled")==="true";
+if(!alreadyDisabled)setActive(a,state.activeVersion===slug);
+}
 }
 var label=c.querySelector("[data-version-trigger-label]");
 if(label){
@@ -278,7 +311,14 @@ label.textContent=activeLabel!=null?activeLabel:state.activeVersion;
 }
 }
 }
-rewire();
+// The initial call is deferred to DOMContentLoaded when the script (inline in
+// <header>, which parses before <article>) would otherwise run before the
+// article element exists. Running early would read a missing ATTR as "no
+// unavailable slugs" and clobber the SSR-correct disabled state with
+// everything-enabled \u2014 a first-paint variant of the bug this rewire exists
+// to fix (see the doc comment above; SSR already rendered the right state for
+// this page, so a brief deferral loses nothing).
+if(document.readyState==="loading"){document.addEventListener("DOMContentLoaded",rewire);}else{rewire();}
 document.addEventListener(${JSON.stringify(AFTER_NAVIGATE_EVENT)},rewire);
 })();`;
 export {

package/dist/inline-version-switcher/index.d.ts

@@ -23,6 +23,24 @@ export interface InlineVersionSwitcherDeps {
     versionedDocsUrl: (slug: string, versionSlug: string, lang?: string) => string;
     /** Prefix a path with the configured base directory. */
     withBase: (path: string) => string;
+    /**
+     * Slugs of configured versions where the given (slug, locale) is NOT
+     * available — passed straight through as `<VersionSwitcher
+     * unavailableVersions>` so absent pages render disabled instead of 404
+     * links (#3215). Returns `undefined` when there is no availability data to
+     * compute (the shared helper already handles the no-slug/no-versions
+     * gates — see `version-availability`).
+     *
+     * Optional — `./inline-version-switcher` is a documented frozen-1.0 public
+     * subpath (`packages/zudo-doc/CLAUDE.md`/`API.md`), so a pre-#3215 caller
+     * that hand-constructs `InlineVersionSwitcherDeps` without this field must
+     * keep compiling. Omitting it reports no version as unavailable — byte-for-
+     * byte the pre-#3215 rendering — so unlike the nav wrappers' optional
+     * `versionedDocsUrl` (whose absence yields hrefs that escape the version
+     * silo) there is nothing degraded to warn about, and this builder runs on
+     * every versioned doc page so a warning would be pure per-page noise.
+     */
+    getUnavailableVersions?: (slug: string | undefined, locale: string) => ReadonlySet<string> | undefined;
 }
 /**
  * Build the `buildInlineVersionSwitcher` function bound to the host's settings

package/dist/inline-version-switcher/index.js

@@ -3,7 +3,7 @@ import {
   VersionSwitcher
 } from "../i18n-version/index.js";
 function createInlineVersionSwitcher(deps) {
-  const { settings, defaultLocale, t, docsUrl, versionedDocsUrl, withBase } = deps;
+  const { settings, defaultLocale, t, docsUrl, versionedDocsUrl, withBase, getUnavailableVersions } = deps;
   function buildInlineVersionSwitcher(slug, locale, currentVersion) {
     if (!settings.versions || settings.versions.length === 0) return void 0;
     const isNonDefaultLocale = locale !== defaultLocale;
@@ -21,6 +21,7 @@ function createInlineVersionSwitcher(deps) {
       unavailable: t("version.switcher.unavailable", locale),
       allVersions: t("version.switcher.allVersions", locale)
     };
+    const unavailableVersions = getUnavailableVersions?.(slug, locale);
     return /* @__PURE__ */ jsx(
       VersionSwitcher,
       {
@@ -32,6 +33,7 @@ function createInlineVersionSwitcher(deps) {
         latestUrl,
         versionsPageUrl,
         versionUrls,
+        unavailableVersions,
         labels,
         idSuffix: "inline"
       }