@takazudo/zudo-doc 4.4.13 → 5.0.0

package/dist/theme-packs/broadsheet/meta.json

@@ -4,7 +4,7 @@
   "name": "Broadsheet",
   "description": "Newspaper editorial — Playfair masthead, Oxford ink rules, a red drop cap, and a night-edition dark mode.",
   "mode": "light",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "fonts": {
     "sans": "Source Serif 4",
     "mono": "Courier Prime",

package/dist/theme-packs/broadsheet/pack.css

@@ -187,6 +187,15 @@ html[data-theme-pack="broadsheet"] body {
   background-attachment: fixed;
 }
 
+/* Touch devices: background-attachment:fixed is unsupported (iOS Safari) or
+   repaint-heavy on scroll — fall back to scroll attachment. Catalog-wide
+   convention from issue #3070. */
+@media (pointer: coarse) {
+  html[data-theme-pack="broadsheet"] body {
+    background-attachment: scroll;
+  }
+}
+
 /* masthead: Playfair black wordmark over a thick-thin Oxford rule */
 html[data-theme-pack="broadsheet"] header[data-header] {
   border-bottom: 3px solid var(--zd-fg);

package/dist/theme-packs/drift/meta.json

@@ -4,7 +4,7 @@
   "name": "Drift",
   "description": "Floaty slate-blue comfort dark for long reading — soft glows in place of borders, gentle elevation, relaxed Plex type.",
   "mode": "dark",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "fonts": {
     "sans": "IBM Plex Sans",
     "mono": "IBM Plex Mono",

package/dist/theme-packs/drift/pack.css

@@ -210,6 +210,15 @@ html[data-theme-pack="drift"] body {
     );
   background-attachment: fixed;
 }
+
+/* Touch devices: background-attachment:fixed is unsupported (iOS Safari) or
+   repaint-heavy on scroll — fall back to scroll attachment. Catalog-wide
+   convention from issue #3070. */
+@media (pointer: coarse) {
+  html[data-theme-pack="drift"] body {
+    background-attachment: scroll;
+  }
+}
 /* the base stylesheet sets `.zd-content { line-height: var(--leading-relaxed) }`
    (1.625), which beats the inherited body value — restate the relaxed
    1.75 rhythm on the prose container itself */

package/dist/theme-packs/fjord/meta.json

@@ -4,7 +4,7 @@
   "name": "Fjord",
   "description": "Polar-night blue under a faint aurora — frost-cyan accents, icy borders, snow-white text. Cold nordic calm.",
   "mode": "dark",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "fonts": {
     "sans": "Inter",
     "mono": "JetBrains Mono",

package/dist/theme-packs/fjord/pack.css

@@ -170,6 +170,15 @@ html[data-theme-pack="fjord"] body {
   background-attachment: fixed;
 }
 
+/* Touch devices: background-attachment:fixed is unsupported (iOS Safari) or
+   repaint-heavy on scroll — fall back to scroll attachment. Catalog-wide
+   convention from issue #3070. */
+@media (pointer: coarse) {
+  html[data-theme-pack="fjord"] body {
+    background-attachment: scroll;
+  }
+}
+
 html[data-theme-pack="fjord"] {
   scrollbar-color: color-mix(in oklch, var(--zd-muted) 45%, transparent) transparent;
 }

package/dist/theme-packs/hearth/meta.json

@@ -4,7 +4,7 @@
   "name": "Hearth",
   "description": "Warm cream & brick-red fireside docs — Fraunces headings, amber code blocks, ember-glow dark mode.",
   "mode": "light",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "fonts": {
     "sans": "Nunito",
     "mono": "Spline Sans Mono",

package/dist/theme-packs/hearth/pack.css

@@ -172,6 +172,15 @@ html[data-theme-pack="hearth"] body {
   background-attachment: fixed;
 }
 
+/* Touch devices: background-attachment:fixed is unsupported (iOS Safari) or
+   repaint-heavy on scroll — fall back to scroll attachment. Catalog-wide
+   convention from issue #3070. */
+@media (pointer: coarse) {
+  html[data-theme-pack="hearth"] body {
+    background-attachment: scroll;
+  }
+}
+
 /* header: warm mantelpiece — soft gradient, warm hairline, brown
    shadow */
 html[data-theme-pack="hearth"] header[data-header] {

package/dist/theme-packs/hollow/meta.json

@@ -4,7 +4,7 @@
   "name": "Hollow",
   "description": "Dark violet space — neon pink headings, violet links, a quiet starfield, and razor-square midnight chrome.",
   "mode": "dark",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "fonts": {
     "sans": "Space Grotesk",
     "mono": "Space Mono",

package/dist/theme-packs/hollow/pack.css

@@ -209,6 +209,15 @@ html[data-theme-pack="hollow"] body {
   background-attachment: fixed;
 }
 
+/* Touch devices: background-attachment:fixed is unsupported (iOS Safari) or
+   repaint-heavy on scroll — fall back to scroll attachment. Catalog-wide
+   convention from issue #3070. */
+@media (pointer: coarse) {
+  html[data-theme-pack="hollow"] body {
+    background-attachment: scroll;
+  }
+}
+
 /* sidebar floats transparently over the starfield */
 html[data-theme-pack="hollow"] #desktop-sidebar {
   background-color: transparent;

package/dist/theme-packs/matcha/meta.json

@@ -4,7 +4,7 @@
   "name": "Matcha",
   "description": "Green tea ceremony — deep matcha on warm cream, mincho headings, zen whitespace, tea-foam surfaces in both modes.",
   "mode": "light",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "fonts": {
     "sans": "Zen Kaku Gothic New",
     "mono": "M PLUS 1 Code",

package/dist/theme-packs/matcha/pack.css

@@ -183,6 +183,15 @@ html[data-theme-pack="matcha"] body {
   background-attachment: fixed;
 }
 
+/* Touch devices: background-attachment:fixed is unsupported (iOS Safari) or
+   repaint-heavy on scroll — fall back to scroll attachment. Catalog-wide
+   convention from issue #3070. */
+@media (pointer: coarse) {
+  html[data-theme-pack="matcha"] body {
+    background-attachment: scroll;
+  }
+}
+
 /* zen prose: let the reading column breathe. The package flow-space
    rhythm (vsp-2xl h2 / vsp-xl h3) already sits within 0.1rem of the
    prototype's spacing, so only the line-height lever is ported. */

package/dist/theme-packs/nocturne/meta.json

@@ -4,7 +4,7 @@
   "name": "Nocturne",
   "description": "Purple midnight — velvet aubergine depths, lavender links, and muted gold hairlines. Elegant, never neon.",
   "mode": "dark",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "fonts": {
     "sans": "Manrope",
     "mono": "IBM Plex Mono",

package/dist/theme-packs/nocturne/pack.css

@@ -216,6 +216,15 @@ html[data-theme-pack="nocturne"] body {
   background-attachment: fixed;
 }
 
+/* Touch devices: background-attachment:fixed is unsupported (iOS Safari) or
+   repaint-heavy on scroll — fall back to scroll attachment. Catalog-wide
+   convention from issue #3070. */
+@media (pointer: coarse) {
+  html[data-theme-pack="nocturne"] body {
+    background-attachment: scroll;
+  }
+}
+
 /* header: velvet band under a gold hairline */
 html[data-theme-pack="nocturne"] header[data-header] {
   border-bottom-color: light-dark(oklch(0.53 0.105 85 / 0.45), oklch(0.78 0.105 87 / 0.45));

package/dist/theme-packs/observatory/meta.json

@@ -4,7 +4,7 @@
   "name": "Observatory",
   "description": "Night-sky atlas: star-field depth, constellation-line rules, nebula violet and comet gold over astronomer's navy.",
   "mode": "dark",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "fonts": {
     "sans": "Jost",
     "mono": "Space Mono",

package/dist/theme-packs/observatory/pack.css

@@ -258,6 +258,15 @@ html[data-theme-pack="observatory"] body {
   letter-spacing: 0.005em;
 }
 
+/* Touch devices: background-attachment:fixed is unsupported (iOS Safari) or
+   repaint-heavy on scroll — fall back to scroll attachment. Catalog-wide
+   convention from issue #3070. */
+@media (pointer: coarse) {
+  html[data-theme-pack="observatory"] body {
+    background-attachment: scroll;
+  }
+}
+
 /* header — observatory signage over a gold→violet ecliptic rule */
 html[data-theme-pack="observatory"] header[data-header] {
   border-image: linear-gradient(
@@ -319,6 +328,15 @@ html[data-theme-pack="observatory"] #desktop-sidebar {
     320px 320px;
   background-attachment: fixed;
 }
+
+/* Touch devices: background-attachment:fixed is unsupported (iOS Safari) or
+   repaint-heavy on scroll — fall back to scroll attachment. Catalog-wide
+   convention from issue #3070. */
+@media (pointer: coarse) {
+  html[data-theme-pack="observatory"] #desktop-sidebar {
+    background-attachment: scroll;
+  }
+}
 html[data-theme-pack="observatory"] #desktop-sidebar a {
   border-radius: 0;
 }

package/dist/theme-packs/onyx/meta.json

@@ -4,7 +4,7 @@
   "name": "Onyx",
   "description": "Luxury noir — jet black, champagne serif headings, and a single gold hairline accent. Watch-brand restraint.",
   "mode": "dark",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "fonts": {
     "sans": "Jost",
     "mono": "IBM Plex Mono",

package/dist/theme-packs/onyx/pack.css

@@ -215,6 +215,15 @@ html[data-theme-pack="onyx"] body {
   letter-spacing: 0.005em;
 }
 
+/* Touch devices: background-attachment:fixed is unsupported (iOS Safari) or
+   repaint-heavy on scroll — fall back to scroll attachment. Catalog-wide
+   convention from issue #3070. */
+@media (pointer: coarse) {
+  html[data-theme-pack="onyx"] body {
+    background-attachment: scroll;
+  }
+}
+
 /* header: engraved nameplate over a gold hairline */
 html[data-theme-pack="onyx"] header[data-header] {
   border-bottom: 1px solid color-mix(in oklch, var(--zd-accent) 38%, transparent);

package/dist/theme-packs/sakura/meta.json

@@ -4,7 +4,7 @@
   "name": "Sakura",
   "description": "Cherry-blossom pastels — blush-white paper, plum ink, and rose accents on petal-soft corners; dark mode is yozakura, night blossoms under lantern-pink light.",
   "mode": "light",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "fonts": {
     "sans": "Nunito",
     "mono": "M PLUS 1 Code",

package/dist/theme-packs/sakura/pack.css

@@ -194,6 +194,15 @@ html[data-theme-pack="sakura"] body {
   background-attachment: fixed;
 }
 
+/* Touch devices: background-attachment:fixed is unsupported (iOS Safari) or
+   repaint-heavy on scroll — fall back to scroll attachment. Catalog-wide
+   convention from issue #3070. */
+@media (pointer: coarse) {
+  html[data-theme-pack="sakura"] body {
+    background-attachment: scroll;
+  }
+}
+
 /* header — a blush veil fading toward the right, petal hairline */
 html[data-theme-pack="sakura"] header[data-header] {
   background-image: linear-gradient(

package/dist/theme-packs/sumi/meta.json

@@ -4,7 +4,7 @@
   "name": "Sumi",
   "description": "Sumi-e ink on washi — bold mincho brush headings, deep black strokes, one vermillion hanko seal accent.",
   "mode": "light",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "fonts": {
     "sans": "Zen Kaku Gothic New",
     "mono": "IBM Plex Mono",

package/dist/theme-packs/sumi/pack.css

@@ -239,6 +239,15 @@ html[data-theme-pack="sumi"] body {
   background-attachment: fixed;
 }
 
+/* Touch devices: background-attachment:fixed is unsupported (iOS Safari) or
+   repaint-heavy on scroll — fall back to scroll attachment. Catalog-wide
+   convention from issue #3070. */
+@media (pointer: coarse) {
+  html[data-theme-pack="sumi"] body {
+    background-attachment: scroll;
+  }
+}
+
 /* header: one decisive ink rule; mincho logo signed with a seal */
 html[data-theme-pack="sumi"] header[data-header] {
   border-bottom: 3px solid var(--zd-fg);

package/dist/theme-packs/timberline/meta.json

@@ -4,7 +4,7 @@
   "name": "Timberline",
   "description": "Forest cabin after dark — pine & umber planks, cream prose, and matte lantern-amber accents; light mode is the same lodge at morning.",
   "mode": "dark",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "fonts": {
     "sans": "Source Sans 3",
     "mono": "JetBrains Mono",

package/dist/theme-packs/timberline/pack.css

@@ -191,6 +191,15 @@ html[data-theme-pack="timberline"] body {
   background-attachment: fixed;
 }
 
+/* Touch devices: background-attachment:fixed is unsupported (iOS Safari) or
+   repaint-heavy on scroll — fall back to scroll attachment. Catalog-wide
+   convention from issue #3070. */
+@media (pointer: coarse) {
+  html[data-theme-pack="timberline"] body {
+    background-attachment: scroll;
+  }
+}
+
 /* header: the lintel beam — umber board over a plank seam (dark
    groove hairline + chamfer highlight catching on the board below) */
 html[data-theme-pack="timberline"] header[data-header] {

package/dist/theme-packs-registry/validator.js

@@ -11,15 +11,28 @@ import {
 function stripComments(css) {
   return css.replace(/\/\*[\s\S]*?\*\//g, "");
 }
-function parseTopLevelRules(css) {
+function parseTopLevelRules(css, onBareStatement) {
   const text = stripComments(css);
   const rules = [];
   const n = text.length;
   let i = 0;
+  const reportBareStatements = (segment) => {
+    if (!onBareStatement) return;
+    const re = /@[a-zA-Z-]+[^{;]*;/g;
+    let m;
+    while ((m = re.exec(segment)) !== null) {
+      onBareStatement(m[0].trim());
+    }
+  };
   while (i < n) {
     const braceIdx = text.indexOf("{", i);
-    if (braceIdx === -1) break;
-    const preludeRaw = text.slice(i, braceIdx).replace(/@[a-zA-Z-]+[^{;]*;/g, "");
+    if (braceIdx === -1) {
+      reportBareStatements(text.slice(i));
+      break;
+    }
+    const preludeSegment = text.slice(i, braceIdx);
+    reportBareStatements(preludeSegment);
+    const preludeRaw = preludeSegment.replace(/@[a-zA-Z-]+[^{;]*;/g, "");
     const prelude = preludeRaw.trim();
     let depth = 1;
     let j = braceIdx + 1;
@@ -38,6 +51,9 @@ function parseTopLevelRules(css) {
 function isFontFaceRule(rule) {
   return /^@font-face\b/i.test(rule.prelude);
 }
+function isMediaRule(rule) {
+  return /^@media\b/i.test(rule.prelude);
+}
 function extractFontFaceFamilies(cssContent) {
   const families = [];
   for (const rule of parseTopLevelRules(cssContent)) {
@@ -86,9 +102,8 @@ function checkCssPresence(dirName, cssContent, issues) {
 }
 function checkScoping(slug, cssContent, issues) {
   const prefix = `html[data-theme-pack="${slug}"]`;
-  for (const rule of parseTopLevelRules(cssContent)) {
-    if (isFontFaceRule(rule)) continue;
-    for (const rawBranch of rule.prelude.split(",")) {
+  const checkPrelude = (prelude) => {
+    for (const rawBranch of prelude.split(",")) {
       const branch = rawBranch.trim();
       if (branch.length === 0) continue;
       if (!branch.startsWith(prefix)) {
@@ -99,6 +114,23 @@ function checkScoping(slug, cssContent, issues) {
         });
       }
     }
+  };
+  for (const rule of parseTopLevelRules(cssContent)) {
+    if (isFontFaceRule(rule)) continue;
+    if (isMediaRule(rule)) {
+      const innerRules = parseTopLevelRules(rule.body, (statement) => {
+        issues.push({
+          rule: "scoping",
+          severity: "error",
+          message: `at-rule statement "${statement}" inside @media is not a pack-scoped rule and is not allowed`
+        });
+      });
+      for (const innerRule of innerRules) {
+        checkPrelude(innerRule.prelude);
+      }
+      continue;
+    }
+    checkPrelude(rule.prelude);
   }
 }
 function checkKnownTokenNames(cssContent, issues) {

package/dist/toc-prepaint/index.d.ts

@@ -0,0 +1,60 @@
+/** @jsxRuntime automatic */
+/** @jsxImportSource preact */
+import type { JSX } from "preact";
+export interface TocPrepaintProps {
+    /**
+     * Whether the page actually renders the package's own default TOC (i.e.
+     * `shouldRenderToc && !customTocIsPresent`, computed by the shell). When
+     * false there is no default TOC for the toggle to collapse — the shell
+     * either has no TOC at all or renders a custom `hostBindings.Toc` override.
+     */
+    shouldRenderDefaultToc?: boolean;
+}
+/** Settings subset read by the toc-prepaint factories. */
+export interface TocPrepaintSettings {
+    tocToggle?: boolean;
+}
+/**
+ * Shared gate for BOTH toc-prepaint factories: the head pre-paint `<script>`
+ * and the `afterSidebar` toggle Island must appear on exactly the same pages,
+ * so they read the same predicate here rather than each inlining
+ * `settings.tocToggle && shouldRenderDefaultToc` (a one-sided edit could
+ * otherwise let the script and the button desync — the #2571 pattern).
+ *
+ * The predicate cannot know whether a custom Toc exists on its own — the
+ * shell computes `shouldRenderDefaultToc` and passes it in.
+ */
+export declare function tocPrepaintActive(settings: TocPrepaintSettings, shouldRenderDefaultToc?: boolean): boolean;
+/**
+ * Pre-paint inline script body: restore persisted TOC visibility to
+ * `<html data-toc-hidden>` before first paint to avoid a hard-reload flash.
+ *
+ * A tiny synchronous IIFE that reads `localStorage[TOC_STORAGE_KEY]` and
+ * sets `data-toc-hidden` only when the stored value is exactly "false"
+ * (the collapsed preference) — the default (visible) needs no attribute and
+ * causes no layout shift. Silently no-ops in privacy / disabled-storage modes.
+ *
+ * The storage key is interpolated from `TOC_STORAGE_KEY` so it stays in
+ * sync with the island's reader; the `data-toc-hidden` attribute name is a
+ * literal here (the island's `setDataAttribute` hardcodes the same literal —
+ * keep the two in sync). Intended for `<head>` placement so it executes before
+ * the `.zd-toc-col` TOC column is painted.
+ */
+export declare const TOC_VISIBILITY_PREPAINT_SCRIPT: string;
+/**
+ * Create a `TocVisibilityPrepaint` component bound to the host's settings.
+ *
+ * Returns the pre-paint `<script>` (for the page `<head>`) when
+ * `settings.tocToggle` is enabled AND the page actually renders the default
+ * TOC; returns `undefined` otherwise — the SAME gating as
+ * {@link createTocPrepaint}, so the head script and the afterSidebar toggle
+ * button always appear together.
+ */
+export declare function createTocVisibilityPrepaint(settings: TocPrepaintSettings): (props: TocPrepaintProps) => JSX.Element | undefined;
+/**
+ * Create a `TocPrepaint` component bound to the host's settings.
+ *
+ * The host stub calls this once with `{ tocToggle: settings.tocToggle }`
+ * and re-exports the result.
+ */
+export declare function createTocPrepaint(settings: TocPrepaintSettings): (props: TocPrepaintProps) => JSX.Element | undefined;

package/dist/toc-prepaint/index.js

@@ -0,0 +1,44 @@
+import { Fragment, jsx } from "preact/jsx-runtime";
+import { Island } from "@takazudo/zfb";
+import {
+  DesktopTocToggle,
+  TOC_STORAGE_KEY
+} from "../desktop-toc-toggle-island/index.js";
+function tocPrepaintActive(settings, shouldRenderDefaultToc) {
+  return Boolean(settings.tocToggle) && Boolean(shouldRenderDefaultToc);
+}
+const TOC_VISIBILITY_PREPAINT_SCRIPT = `(function(){try{if(localStorage.getItem(${JSON.stringify(
+  TOC_STORAGE_KEY
+)})==='false'){document.documentElement.setAttribute('data-toc-hidden','');}}catch(e){}})();`;
+function createTocVisibilityPrepaint(settings) {
+  function TocVisibilityPrepaint({
+    shouldRenderDefaultToc
+  }) {
+    if (!tocPrepaintActive(settings, shouldRenderDefaultToc)) return void 0;
+    return /* @__PURE__ */ jsx(
+      "script",
+      {
+        dangerouslySetInnerHTML: { __html: TOC_VISIBILITY_PREPAINT_SCRIPT }
+      }
+    );
+  }
+  return TocVisibilityPrepaint;
+}
+function createTocPrepaint(settings) {
+  function TocPrepaint({
+    shouldRenderDefaultToc
+  }) {
+    if (!tocPrepaintActive(settings, shouldRenderDefaultToc)) return void 0;
+    return /* @__PURE__ */ jsx(Fragment, { children: Island({
+      when: "load",
+      children: /* @__PURE__ */ jsx(DesktopTocToggle, {})
+    }) });
+  }
+  return TocPrepaint;
+}
+export {
+  TOC_VISIBILITY_PREPAINT_SCRIPT,
+  createTocPrepaint,
+  createTocVisibilityPrepaint,
+  tocPrepaintActive
+};

package/dist/url-helpers/index.d.ts

@@ -20,7 +20,7 @@ export interface UrlHelpers {
     docsUrl(slug: string, lang?: string): string;
     isExternal(href: string): boolean;
     resolveHref(href: string): string;
-    navHref(path: string, lang: string | undefined, currentVersion: string | undefined): string;
+    navHref(path: string, lang: string | undefined, currentVersion: string | undefined, versioned?: boolean): string;
     getPathForLocale(path: string, currentLang: string, targetLang: string): string;
     buildLocaleLinks(currentPath: string, currentLang: string): LocaleLink[];
     isDefaultLocaleOnlyPath(path: string): boolean;

package/dist/url-helpers/index.js

@@ -35,9 +35,9 @@ function makeUrlHelpers(settings, i18n) {
   function resolveHref(href) {
     return isExternal(href) ? href : withBase(href);
   }
-  function navHref(path, lang, currentVersion) {
+  function navHref(path, lang, currentVersion, versioned = true) {
     const isNonDefaultLocale = lang != null && lang !== defaultLocale && !isDefaultLocaleOnlyPath(path);
-    const versionPrefix = currentVersion ? `/v/${currentVersion}` : "";
+    const versionPrefix = versioned && currentVersion ? `/v/${currentVersion}` : "";
     return withBase(
       isNonDefaultLocale ? `${versionPrefix}/${lang}${path}` : `${versionPrefix}${path}`
     );

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

@@ -0,0 +1,75 @@
+import type { DocPageEntry, DocNavNode } from "../doc-page-props/index.js";
+import type { CategoryMeta } from "../sidebar-tree/index.js";
+/** Structural subset of `NavSourceDocs` this module reads. */
+export interface VersionAvailabilityNavSource {
+    docs: DocPageEntry[];
+    navDocs: DocPageEntry[];
+    categoryMeta: Map<string, CategoryMeta>;
+}
+/** Injected dependencies for {@link createGetUnavailableVersions}. */
+export interface VersionAvailabilityDeps {
+    /** Configured versions to check availability for (`false` / empty ⇒ no-op). */
+    versions: Array<{
+        slug: string;
+    }> | false;
+    /**
+     * Identity-stable nav-source resolver (`resolveNavSource` from
+     * `nav-source-docs`) — already memoized per (locale, version, options), so
+     * a cache miss in {@link createGetUnavailableVersions} is cheap.
+     */
+    resolveNavSource: (locale: string, versionSlug: string, options?: {
+        applyDefaultLocaleOnlyFilter?: boolean;
+        keepUnlisted?: boolean;
+    }) => VersionAvailabilityNavSource;
+    /** Canonical route slug for a zfb content slug — injected, not ambient. */
+    toRouteSlug: (entrySlug: string) => string;
+    /**
+     * Nav-tree builder, already bound to a href builder by the caller (hrefs
+     * are irrelevant here — the tree is only walked to discover auto-index
+     * nodes via {@link VersionAvailabilityDeps.collectAutoIndexNodes}).
+     */
+    buildNavTree: (docs: DocPageEntry[], locale: string, categoryMeta: Map<string, CategoryMeta>) => DocNavNode[];
+    /** Category nodes with children but no page of their own — real routes
+     *  with no corresponding docs entry (see module header). */
+    collectAutoIndexNodes: (tree: DocNavNode[]) => DocNavNode[];
+}
+/**
+ * Build `getUnavailableVersions(slug, locale)`, bound to the injected deps.
+ *
+ * Returns `undefined` when there is no current slug to test (e.g. a
+ * no-current-slug header render on the home page) or when versioning is not
+ * configured — NEVER mark every archive unavailable just because there is no
+ * page to test against.
+ *
+ * Each version's available-slug Set is cached here keyed by BOTH locale and
+ * version (`${locale}\n${versionSlug}`) — a version-slug-only key would be
+ * wrong, because a versioned locale merge differs per language.
+ */
+export declare function createGetUnavailableVersions(deps: VersionAvailabilityDeps): (slug: string | undefined, locale: string) => ReadonlySet<string> | undefined;
+/**
+ * `data-*` attribute name the client payload rides on — see the module
+ * header's "Client payload contract" section for the full spelling/format
+ * contract. Exported so a future consumer (#3244) reads the same literal
+ * instead of hand-copying the string.
+ */
+export declare const UNAVAILABLE_VERSIONS_ATTR = "data-doc-unavailable-versions";
+/**
+ * Serialize a `getUnavailableVersions()` result into the `data-*` attribute
+ * bag `<DocPageShell>` spreads onto `<article>`. Returns `{}` (no key at
+ * all) for `undefined` input so the attribute is genuinely ABSENT from the
+ * rendered element, preserving the three-state contract documented above —
+ * an empty object here must not be confused with `{ [ATTR]: "" }`.
+ */
+export declare function serializeUnavailableVersions(unavailableVersions: ReadonlySet<string> | undefined): Record<string, string>;
+/**
+ * Enforce the comma-free version-slug constraint the module header's
+ * "Client payload contract" section documents. Shared by BOTH `zudoDoc()`
+ * (`../config.ts`) and `zudoDocPreset()` (`../preset.ts`) — the preset is
+ * itself part of the frozen exported API and documented as directly
+ * spreadable into `defineConfig`, so a consumer calling it straight (bypassing
+ * `zudoDoc()`) must hit the same guard (#3244 codex review finding 2 follow-up).
+ * Throws a `TypeError` naming the offending slug; no-op for `false`/`undefined`.
+ */
+export declare function assertNoCommaInVersionSlugs(versions: ReadonlyArray<{
+    slug: string;
+}> | false | undefined): void;