@takazudo/zudo-doc 4.5.0 → 5.0.1

package/CHANGELOG.md

@@ -4,6 +4,60 @@ All notable changes to `@takazudo/zudo-doc` are documented in this file.
 
 The format is based on Keep a Changelog, and release notes are generated from the changelog MDX pages.
 
+## [5.0.1] - 2026-08-04
+
+### Bug Fixes
+
+- `setup-doc-skill.sh` no longer skips a tracked skill whose global symlink is already correct. The idempotency check compared the literal string stored in the existing symlink against a target built from `MAIN_PROJECT_DIR`, which is derived from `git worktree list` and is therefore always the **physical** path. When the project or any parent directory sits behind a symlink — a symlinked `$HOME`, a symlinked checkout, or macOS's `$TMPDIR` (`/var` → `/private/var`) — the two forms name the same directory but differ as strings, so the script mis-read its own correct link as foreign and printed a spurious `already links to ...` warning instead of no-opping. It now compares where the link actually lands, via a portable `physical_dir` helper (`cd` + `pwd -P`, since stock macOS ships no `realpath(1)` and BSD `readlink` has no `-f`). The dangling-symlink replacement path and the D4 safe-link policy are unchanged — nothing the script does not own is ever claimed or deleted (b6a226c, 76a39c0)
+- Harden that same helper against unresolvable directories: it now falls back to its raw input on any resolution failure. An unreadable directory made `cd` fail and the subshell yield an empty string, so two different unreadable paths both collapsed to `""` and compared equal, which would have silently skipped a link that should have been created. `cd`'s permission-denied output is suppressed (76a39c0)
+
+### Other Changes
+
+- Add a regression test that reaches the skill directory through a deliberate symlinked alias, so the defect above reproduces on Linux as well. The original bug was invisible to CI because only macOS symlinks `$TMPDIR`; the test was verified to fail against the pre-fix script (b6a226c)
+
+## [5.0.0] - 2026-08-04
+
+### Breaking Changes
+
+- The `@takazudo/zfb` family peer range moves from `^1.1.0` to `^2.1.0`. Consumers must upgrade `@takazudo/zfb`, `@takazudo/zfb-md-wasm`, and `@takazudo/zfb-runtime` in lockstep; `@takazudo/design-token-lint` also moves from 1.x to 2.x (d23e47a8, fb91919f)
+- The `githubAutolinks` feature and its `githubAutolinksRepo` setting are removed. A project still passing `githubAutolinksRepo` now fails at runtime with an explicit rejection rather than silently ignoring it, and the config shim likewise rejects zfb 2.0.0's removed `githubAutolinks` key (3d4a8ca7, 4c03befc, 255676da)
+- `strictContentBridge` is enabled by default in this repo's config and re-points the b4push/CI wiring — a content-bridge fallback now fails a plain `pnpm build` instead of only tripping the allowlist-gated b4push step (#3234, d3035f68)
+- The shared base `tsconfig` flips its JSX mode to `react-jsx` with `jsxImportSource: preact`, and `@types/react` is dropped from the scaffolded devDependencies. Projects that relied on the React typings being present must add them back explicitly (#3182, 705c3957, be91c050)
+
+### Features
+
+- Desktop TOC visibility toggle — a new `tocToggle` setting adds a prepaint-backed show/hide control for the desktop table of contents, wired through the generator, the showcase, and the sidebar fixture, with e2e coverage. The claim is scoped to default-TOC pages (c5a26102, 3f851196, ed1f6887, 304ce68d, 409b0bfe, 5301b011)
+- New `entryDocSlug` and `headerNav` versioned config fields, letting a versioned site name its entry document and carry version context through header navigation (#3217, 0d42ffbd, e56c4dee)
+- Version switcher now recomputes its disabled state across SPA navigation — each page emits an unavailable-version payload into the swapped content and the switcher rewires on `after-swap` (faa0e8aa, d2a3fccf)
+- GFM task lists and footnotes are now enabled as a preset default (31c1f253)
+- `strictContentBridge` added as a shell passthrough field so downstream projects can opt into the strict content bridge from their own config (725febec, c1432ffa)
+- Theme packs gain a catalog-wide `(pointer: coarse)` scroll fallback for fixed-attachment layers, and the pack validator now accepts top-level `@media`-wrapped pack-scoped rules (ee973b27, 594b0486)
+- `create-zudo-doc` ships a default `public/` favicon set in the base template, with an SVG favicon link emitted ahead of the `.ico`/`.png` entries (a9d100bc, 19d11f8d)
+- The safelist checker gains a `safelist-ok` marker escape hatch plus honest remediation text (150925a4)
+
+### Bug Fixes
+
+- Restore desktop TOC sticky scroll-follow, with an e2e regression guard (ab25912a, ac7d3fc0)
+- Version availability is now computed from real route generation rather than an approximation, and `unavailableVersions` is computed for both version switchers (01409a94, a820304b)
+- An absent version-availability payload now leaves the disabled state untouched instead of clearing it, and the switcher rewire is deferred to `DOMContentLoaded` (6593e0c0, d5d6b586)
+- Thread `currentVersion` into the `CategoryNav` / `CategoryTreeNav` / `SiteTreeNav` wrappers so versioned sites link correctly from nav cards (ddeaa6da)
+- `entryDocSlug` is optional and locale-aware in the versions page (20890f21)
+- The zfb config shim re-exports `zfb/config` instead of hand-copying its shape, and shim-shape validation is now AST-based rather than substring matching, closing three false-negative paths (#3239, #3241, 213f4e5a, ea109c66, 70ad667c)
+- Restore public API back-compat on the versioning deps/node shapes (416baef2)
+- `claude-resources` excludes build directories by basename at any depth rather than only at the top level (6e830dc4)
+- Long delimiter-free inline code identifiers now wrap instead of overflowing (62679947)
+- Rename the TOC island helpers to avoid an island marker-name collision (7c29a6ca)
+- Resolve package-only dependencies in the packed-tarball slow fixtures (df23d982)
+
+### Other Changes
+
+- Academia theme pack readability pass: low-opacity rest-state link underline and 0.9rem code blocks (8dbb8f46)
+- Restructure the `CLAUDE.md` hierarchy and fix seven accuracy defects surfaced by the refactor self-review (#3167, fd2124ba, ed8917a4)
+- Repository cleanup — remove six unused dependencies and two dead files, delete host-side source superseded by package-owned equivalents, drop finished-epic scratch/report directories, and correct stale references in the README, config, and b4push skill (332c8406, 6d2f90dd, a40bc5fd, c035c76d, 7869d45b)
+- Record the Tauri Mode 1 CSP verification result and put the icon prerequisite before the build command in the Tauri docs (4a45c00f, 532eb81e, 8a93286e)
+- Test coverage: dogfood snapshot plus e2e fixture/spec coverage for the version-link family, an SPA-navigation guard for the version-switcher disabled state, a wider A2 fixture covering headings/task lists/footnotes/directives, and the locked favicon set mirrored in the target manifest fixture (#3219, #3245, 1a73989b, fab8568d, 0310c8fb, 94e09ceb)
+- Documentation corrections for the content-fallback guard wiring, the e2e fixture-setup fast path, and the safelist-ok example (9047c389, 2bb9a1e1, 70d69842, 66ad3101, 100761b3)
+
 ## [4.5.0] - 2026-08-02
 
 ### Features

package/dist/category-nav/index.d.ts

@@ -3,6 +3,16 @@
 import type { JSX } from "preact";
 /** Minimal nav node shape required by the category-nav factory. */
 export interface CategoryNavNode {
+    /**
+     * Content slug — used by remapVersionedHrefs to rebuild a versioned href.
+     *
+     * Optional — `./category-nav` is a documented frozen-1.0 public subpath
+     * (`packages/zudo-doc/CLAUDE.md`/`API.md`), so a pre-#3218 caller whose
+     * `buildNavTree`/`findNode` implementations emit the older slug-less node
+     * shape must keep compiling. A node without a slug cannot be rebuilt into
+     * its versioned form, so `remapVersionedHrefs` leaves its href untouched.
+     */
+    slug?: string;
     label: string;
     description?: string;
     href?: string;
@@ -38,6 +48,14 @@ export interface CategoryNavWrapperProps {
      * Defaults to defaultLocale when not provided.
      */
     lang?: string;
+    /**
+     * Active version slug for a `/v/{version}` route. Injected via
+     * createMdxComponents() closure alongside `lang` (#3218). When set, the nav
+     * source resolves the version's doc collection and emitted hrefs are
+     * remapped to their versioned form; omitted (latest/unversioned pages)
+     * leaves behavior unchanged.
+     */
+    currentVersion?: string;
     /** Optional extra CSS classes forwarded to the <nav> element. */
     class?: string;
 }
@@ -68,6 +86,19 @@ export interface CategoryNavDeps {
      * Host passes `firstRoutedHref` from `@/utils/docs`.
      */
     firstRoutedHref: (node: CategoryNavNode) => string | undefined;
+    /**
+     * Build a versioned docs URL: `versionedDocsUrl(slug, versionSlug, lang)`.
+     * Host passes `ctx.versionedDocsUrl`. Used to remap the resolved tree's
+     * hrefs into their versioned form when `currentVersion` is set (#3218) —
+     * mirrors the sidebar's `buildSidebarNodes` two-step in `chrome/derive.tsx`.
+     *
+     * Optional — `./category-nav` is a documented frozen-1.0 public subpath
+     * (`packages/zudo-doc/CLAUDE.md`/`API.md`), so a pre-#3218 caller that hand-
+     * constructs `CategoryNavDeps` without this field must keep compiling.
+     * Omitting it while passing `currentVersion` leaves hrefs unversioned (a
+     * loud dev warning is emitted) rather than throwing.
+     */
+    versionedDocsUrl?: (slug: string, versionSlug: string, lang: string) => string;
 }
 /**
  * Create the `CategoryNavWrapper` component bound to the host's nav source

package/dist/category-nav/index.js

@@ -1,18 +1,30 @@
 import { jsx } from "preact/jsx-runtime";
 import { CategoryNav as CategoryNavV2 } from "../nav-indexing/index.js";
+import { remapVersionedHrefs } from "../nav-data-prep/index.js";
 function createCategoryNavWrapper(deps) {
-  const { defaultLocale, resolveNavSource, buildNavTree, findNode, firstRoutedHref } = deps;
+  const { defaultLocale, resolveNavSource, buildNavTree, findNode, firstRoutedHref, versionedDocsUrl } = deps;
   function CategoryNavWrapper({
     category,
     categories,
     lang = defaultLocale,
+    currentVersion,
     class: className
   }) {
     const locale = lang;
-    const { navDocs, categoryMeta } = resolveNavSource(locale, void 0, {
+    const { navDocs, categoryMeta } = resolveNavSource(locale, currentVersion, {
       keepUnlisted: true
     });
-    const tree = buildNavTree(navDocs, locale, categoryMeta);
+    const rawTree = buildNavTree(navDocs, locale, categoryMeta);
+    let tree = rawTree;
+    if (currentVersion) {
+      if (versionedDocsUrl) {
+        tree = remapVersionedHrefs(rawTree, currentVersion, locale, versionedDocsUrl);
+      } else {
+        console.warn(
+          "[zudo-doc] CategoryNavWrapper: currentVersion is set but CategoryNavDeps.versionedDocsUrl was not provided \u2014 nav card hrefs will NOT be remapped into the version."
+        );
+      }
+    }
     let children;
     if (categories !== void 0) {
       children = categories.map((slug) => {

package/dist/category-tree-nav/index.d.ts

@@ -3,6 +3,17 @@
 import type { JSX } from "preact";
 /** Minimal nav node shape required by the category-tree-nav factory. */
 export interface CategoryTreeNavNode {
+    /**
+     * Content slug — used by remapVersionedHrefs to rebuild a versioned href.
+     *
+     * Optional — `./category-tree-nav` is a documented frozen-1.0 public
+     * subpath (`packages/zudo-doc/CLAUDE.md`/`API.md`), so a pre-#3218 caller
+     * whose `buildNavTree`/`findNode` implementations emit the older slug-less
+     * node shape must keep compiling. A node without a slug cannot be rebuilt
+     * into its versioned form, so `remapVersionedHrefs` leaves its href
+     * untouched.
+     */
+    slug?: string;
     label: string;
     description?: string;
     href?: string;
@@ -26,6 +37,14 @@ export interface CategoryTreeNavWrapperProps {
      * Defaults to defaultLocale when not provided.
      */
     lang?: string;
+    /**
+     * Active version slug for a `/v/{version}` route. Injected via
+     * createMdxComponents() closure alongside `lang` (#3218). When set, the nav
+     * source resolves the version's doc collection and emitted hrefs are
+     * remapped to their versioned form; omitted (latest/unversioned pages)
+     * leaves behavior unchanged.
+     */
+    currentVersion?: string;
 }
 /** Injected dependencies for {@link createCategoryTreeNavWrapper}. */
 export interface CategoryTreeNavDeps {
@@ -54,6 +73,19 @@ export interface CategoryTreeNavDeps {
      * Host passes `findNode` from `@/utils/docs`.
      */
     findNode: (tree: CategoryTreeNavNode[], slug: string) => CategoryTreeNavNode | undefined;
+    /**
+     * Build a versioned docs URL: `versionedDocsUrl(slug, versionSlug, lang)`.
+     * Host passes `ctx.versionedDocsUrl`. Used to remap the resolved tree's
+     * hrefs into their versioned form when `currentVersion` is set (#3218) —
+     * mirrors the sidebar's `buildSidebarNodes` two-step in `chrome/derive.tsx`.
+     *
+     * Optional — `./category-tree-nav` is a documented frozen-1.0 public
+     * subpath (`packages/zudo-doc/CLAUDE.md`/`API.md`), so a pre-#3218 caller
+     * that hand-constructs `CategoryTreeNavDeps` without this field must keep
+     * compiling. Omitting it while passing `currentVersion` leaves hrefs
+     * unversioned (a loud dev warning is emitted) rather than throwing.
+     */
+    versionedDocsUrl?: (slug: string, versionSlug: string, lang: string) => string;
 }
 /**
  * Create the `CategoryTreeNavWrapper` component bound to the host's nav source

package/dist/category-tree-nav/index.js

@@ -1,17 +1,29 @@
 import { jsx } from "preact/jsx-runtime";
 import { CategoryTreeNav as CategoryTreeNavV2 } from "../nav-indexing/index.js";
+import { remapVersionedHrefs } from "../nav-data-prep/index.js";
 function createCategoryTreeNavWrapper(deps) {
-  const { defaultLocale, resolveNavSource, buildNavTree, groupSatelliteNodes, findNode } = deps;
+  const { defaultLocale, resolveNavSource, buildNavTree, groupSatelliteNodes, findNode, versionedDocsUrl } = deps;
   function CategoryTreeNavWrapper({
     category,
-    lang = defaultLocale
+    lang = defaultLocale,
+    currentVersion
   }) {
     const locale = lang;
-    const { navDocs, categoryMeta } = resolveNavSource(locale, void 0, {
+    const { navDocs, categoryMeta } = resolveNavSource(locale, currentVersion, {
       keepUnlisted: true
     });
     const rawTree = buildNavTree(navDocs, locale, categoryMeta);
-    const tree = groupSatelliteNodes(rawTree, [category]);
+    const groupedTree = groupSatelliteNodes(rawTree, [category]);
+    let tree = groupedTree;
+    if (currentVersion) {
+      if (versionedDocsUrl) {
+        tree = remapVersionedHrefs(groupedTree, currentVersion, locale, versionedDocsUrl);
+      } else {
+        console.warn(
+          "[zudo-doc] CategoryTreeNavWrapper: currentVersion is set but CategoryTreeNavDeps.versionedDocsUrl was not provided \u2014 nav card hrefs will NOT be remapped into the version."
+        );
+      }
+    }
     const categoryNode = findNode(tree, category);
     const children = categoryNode?.children.filter((c) => c.hasPage || c.children.length > 0) ?? [];
     if (children.length === 0) return null;

package/dist/chrome/derive.d.ts

@@ -64,8 +64,28 @@ export declare function deriveBodyEndIslands(ctx: ChromeContext): (props: import
 /** Derive the DocHistory island: `ctx.hostBindings.DocHistory` when supplied,
  *  else the package no-op stub. */
 export declare function deriveDocHistorySlot(ctx: ChromeContext): typeof DocHistoryStub;
-/** Derive the inline version-switcher builder bound to the context. */
-export declare function deriveInlineVersionSwitcher(ctx: ChromeContext): (slug: string, locale: string, currentVersion?: string) => JSX.Element | undefined;
+/**
+ * Derive `getUnavailableVersions(slug, locale)`, shared by the inline
+ * breadcrumb switcher (`deriveInlineVersionSwitcher` below) and the header
+ * dropdown switcher (`createHeaderWithDefaults`) — the genuinely
+ * multi-factory piece of #3215's availability computation, so both callers
+ * wire the SAME implementation instead of re-deriving the recipe.
+ */
+export declare function deriveGetUnavailableVersions(ctx: ChromeContext): (slug: string | undefined, locale: string) => ReadonlySet<string> | undefined;
+/**
+ * Derive the inline version-switcher builder bound to the context.
+ *
+ * `getUnavailableVersions` is optional so a caller that already built one
+ * (e.g. `createRenderDocPage`, which also emits it as the SPA-rewire client
+ * payload — #3243) can pass that SAME instance instead of a second one being
+ * derived here. `createGetUnavailableVersions` owns a per-(locale, version)
+ * nav-source cache, so two independently-derived instances would each
+ * resolve the nav source and rebuild the auto-index tree from scratch on
+ * their first call per (locale, version) — doubling that work on every
+ * versioned route. Defaults to deriving its own when omitted, so this stays
+ * backward-compatible with a bare `deriveInlineVersionSwitcher(ctx)` call.
+ */
+export declare function deriveInlineVersionSwitcher(ctx: ChromeContext, getUnavailableVersions?: (slug: string | undefined, locale: string) => ReadonlySet<string> | undefined): (slug: string, locale: string, currentVersion?: string) => JSX.Element | undefined;
 /**
  * Derive the locale-aware `createMdxComponents` factory plus the
  * `SiteTreeNavWrapper` (also exposed by `createChrome`). The nav wrappers
@@ -75,9 +95,18 @@ export declare function deriveInlineVersionSwitcher(ctx: ChromeContext): (slug:
  * for the injected package path. The content overrides (Details / HtmlPreview /
  * Island / PresetGenerator + any host extras) come from `ctx.hostBindings.mdxExtras`
  * merged over the package defaults.
+ *
+ * `createMdxComponentsBound(lang, currentVersion?)` (#3218) threads the active
+ * version through to the nav wrappers as a `currentVersion` prop — see
+ * `createMdxComponents()`'s `CategoryNavBound`/etc — so `resolveNavSource`
+ * resolves the version's doc collection and emitted hrefs get remapped via
+ * `versionedDocsUrl`, mirroring `buildSidebarNodes`' two-step above. This works
+ * for BOTH the package-default wrapper (built from `versionedDocsUrl` below)
+ * and a host-supplied `ctx.components` override, since the prop injection
+ * happens one layer up in `createMdxComponents()`, after the wrapper choice.
  */
 export declare function deriveMdxComponents(ctx: ChromeContext): {
-    createMdxComponentsBound: (lang?: string) => Record<string, unknown>;
+    createMdxComponentsBound: (lang?: string, currentVersion?: string) => Record<string, unknown>;
     SiteTreeNavWrapper: FactoryComponent;
 };
 export type { Settings };

package/dist/chrome/derive.js

@@ -21,6 +21,7 @@ import {
   HtmlPreviewWrapper
 } from "../html-preview-wrapper/index.js";
 import { createInlineVersionSwitcher } from "../inline-version-switcher/index.js";
+import { createGetUnavailableVersions } from "../version-availability/index.js";
 import {
   buildRootMenuItems as buildRootMenuItemsBase,
   buildLocaleLinksForNav as buildLocaleLinksForNavBase,
@@ -103,7 +104,7 @@ function deriveNavDataPrep(ctx) {
       currentVersion,
       ctx.settings.headerNav,
       (key, l) => ctx.t(key, l),
-      (path, l, v) => ctx.navHref(path, l, v)
+      (path, l, v, versioned) => ctx.navHref(path, l, v, versioned)
     );
   }
   function buildLocaleLinksForNav(currentPath, lang, localeCount) {
@@ -204,14 +205,27 @@ function deriveBodyEndIslands(ctx) {
 function deriveDocHistorySlot(ctx) {
   return ctx.hostBindings.DocHistory ?? DocHistoryStub;
 }
-function deriveInlineVersionSwitcher(ctx) {
+function deriveGetUnavailableVersions(ctx) {
+  return createGetUnavailableVersions({
+    versions: ctx.settings.versions,
+    resolveNavSource: ctx.resolveNavSource,
+    toRouteSlug: ctx.toRouteSlug,
+    // Hrefs are irrelevant to availability — bound to docsUrl only because
+    // ctx.buildNavTree's buildHref param is required, mirroring the same
+    // throwaway binding route-enumerators/doc-route-entries use.
+    buildNavTree: (docs, locale, categoryMeta) => ctx.buildNavTree(docs, locale, categoryMeta, (slug, loc) => ctx.docsUrl(slug, loc)),
+    collectAutoIndexNodes: ctx.collectAutoIndexNodes
+  });
+}
+function deriveInlineVersionSwitcher(ctx, getUnavailableVersions = deriveGetUnavailableVersions(ctx)) {
   return createInlineVersionSwitcher({
     settings: ctx.settings,
     defaultLocale: ctx.defaultLocale,
     t: ctx.t,
     docsUrl: ctx.docsUrl,
     versionedDocsUrl: ctx.versionedDocsUrl,
-    withBase: ctx.withBase
+    withBase: ctx.withBase,
+    getUnavailableVersions
   });
 }
 function deriveMdxComponents(ctx) {
@@ -225,7 +239,8 @@ function deriveMdxComponents(ctx) {
       (slug, loc) => ctx.docsUrl(slug, loc)
     )),
     findNode: ctx.findNode,
-    firstRoutedHref: ctx.firstRoutedHref
+    firstRoutedHref: ctx.firstRoutedHref,
+    versionedDocsUrl: ctx.versionedDocsUrl
   });
   const CategoryTreeNavWrapper = ctx.components.CategoryTreeNav ?? createCategoryTreeNavWrapper({
     defaultLocale: ctx.defaultLocale,
@@ -237,7 +252,8 @@ function deriveMdxComponents(ctx) {
       (slug, loc) => ctx.docsUrl(slug, loc)
     )),
     groupSatelliteNodes: ctx.groupSatelliteNodes,
-    findNode: ctx.findNode
+    findNode: ctx.findNode,
+    versionedDocsUrl: ctx.versionedDocsUrl
   });
   const SiteTreeNavWrapper = ctx.components.SiteTreeNav ?? createSiteTreeNavWrapper({
     defaultLocale: ctx.defaultLocale,
@@ -249,7 +265,8 @@ function deriveMdxComponents(ctx) {
       (slug, loc) => ctx.docsUrl(slug, loc)
     )),
     groupSatelliteNodes: ctx.groupSatelliteNodes,
-    getCategoryOrder: ctx.getCategoryOrder
+    getCategoryOrder: ctx.getCategoryOrder,
+    versionedDocsUrl: ctx.versionedDocsUrl
   });
   function HtmlPreviewBound(props) {
     return HtmlPreviewWrapper({
@@ -266,10 +283,11 @@ function deriveMdxComponents(ctx) {
     PresetGenerator: (_props) => null
   };
   const mdxExtras = { ...mdxExtrasDefault, ...ctx.hostBindings.mdxExtras ?? {} };
-  function createMdxComponentsBound(lang = ctx.defaultLocale) {
+  function createMdxComponentsBound(lang = ctx.defaultLocale, currentVersion) {
     return createMdxComponents({
       settings: ctx.settings,
       locale: lang,
+      currentVersion,
       navData: {
         CategoryNav: CategoryNavWrapper,
         CategoryTreeNav: CategoryTreeNavWrapper,
@@ -289,6 +307,7 @@ export {
   deriveColorSchemeGenerators,
   deriveComposeMetaTitle,
   deriveDocHistorySlot,
+  deriveGetUnavailableVersions,
   deriveInlineVersionSwitcher,
   deriveMdxComponents,
   deriveNavDataPrep,

package/dist/code-syntax/mermaid-init-script.d.ts

@@ -4,13 +4,12 @@
  *
  * Pinned to a specific minor.patch (not the bare `@11` major) so the
  * runtime version is byte-stable across deploys; floating on the major
- * would silently pull in upstream theme-API or behaviour changes the
- * SSR-time mermaid in package.json hasn't been pinned to. Bump policy:
- * raise this string in the same PR that bumps `mermaid` in
- * package.json so the SSR-time and runtime mermaid versions stay
- * matched. Cross-major jumps need an extra parity smoke (`pnpm build`
- * and a manual diagram render) since esm.sh's exports drift between
- * majors.
+ * would silently pull in upstream theme-API or behaviour changes. Bump
+ * policy: there is no `mermaid` package.json dependency to keep in sync
+ * with — this constant is the sole source of truth for the mermaid
+ * version this project ships. Cross-major jumps need an extra parity
+ * smoke (`pnpm build` and a manual diagram render) since esm.sh's
+ * exports drift between majors.
  *
  * Exported (rather than baked into the template) so consumers and
  * tests can override the URL — e.g. self-hosted mirrors, version-

package/dist/config.d.ts

@@ -127,6 +127,15 @@ export interface ZudoDocConfig {
      * @default "src/content/docs"
      */
     docsDir?: string;
+    /**
+     * Route slug of the doc page the versions page links to as the "latest
+     * docs" entry point (and as each past version's docs link). Convention: no
+     * leading/trailing slashes, e.g. `"getting-started"` or
+     * `"overview/getting-started"`. Not validated at runtime — an invalid slug
+     * simply 404s.
+     * @default "getting-started"
+     */
+    entryDocSlug?: string;
     /**
      * Default locale code (unprefixed routes).
      * @default "en"
@@ -158,11 +167,6 @@ export interface ZudoDocConfig {
      * @default false
      */
     githubUrl?: string | false;
-    /**
-     * "owner/repo" — enables `#123` / SHA autolinks in markdown. Omit to disable.
-     * @default undefined
-     */
-    githubAutolinksRepo?: string;
     /**
      * Canonical site origin (e.g. `"https://example.com"`) for sitemap /
      * canonical / og:url. Empty = not set.
@@ -286,6 +290,11 @@ export interface ZudoDocConfig {
      * @default false
      */
     sidebarToggle?: boolean;
+    /**
+     * Enable the desktop TOC collapse toggle.
+     * @default false
+     */
+    tocToggle?: boolean;
     /**
      * Enable click-to-enlarge for content images.
      * @default false
@@ -464,6 +473,14 @@ export interface ZudoDocConfig {
      * @default undefined
      */
     bundle?: BundleConfig;
+    /**
+     * Build-only gate that fails `zfb build` when a collection entry falls
+     * back to `<pre data-zfb-content-fallback>` (mirrors zfb's
+     * `Config::strict_content_bridge`, zfb 2.0.0). Omit to leave zfb's own
+     * default (`false`) in effect.
+     * @default undefined (zfb's own default, `false`, applies)
+     */
+    strictContentBridge?: boolean;
 }
 /**
  * Build a complete `ZfbConfig` from user config, defaulting every field.

package/dist/config.js

@@ -3,6 +3,7 @@ import { buildDocsSchema as defaultBuildDocsSchema } from "./docs-schema/index.j
 import { defaultDirectiveVocabulary } from "./directive-vocabulary-defaults/index.js";
 import { defaultTranslations } from "./i18n-defaults/index.js";
 import { defaultColorSchemes } from "./color-schemes-defaults/index.js";
+import { assertNoCommaInVersionSlugs } from "./version-availability/index.js";
 const DEFAULT_SETTINGS = {
   colorScheme: "Default Dark",
   colorMode: {
@@ -19,6 +20,7 @@ const DEFAULT_SETTINGS = {
   home: { wide: false },
   minifyHtml: true,
   docsDir: "src/content/docs",
+  entryDocSlug: "getting-started",
   defaultLocale: "en",
   locales: {},
   mermaid: true,
@@ -55,6 +57,7 @@ const DEFAULT_SETTINGS = {
   tocMaxDepth: 4,
   sidebarResizer: false,
   sidebarToggle: false,
+  tocToggle: false,
   imageEnlarge: false,
   findInPage: false,
   dynamicPageTransition: false,
@@ -80,10 +83,16 @@ function zudoDoc(user = {}) {
       "headingIdStrategy is no longer supported; heading IDs are always hierarchical"
     );
   }
+  if ("githubAutolinksRepo" in user) {
+    throw new TypeError(
+      "githubAutolinksRepo is no longer supported; the githubAutolinks markdown feature was removed"
+    );
+  }
   const {
     port,
     adapter,
     bundle,
+    strictContentBridge,
     buildDocsSchema: userBuildDocsSchema,
     colorSchemes: userColorSchemes,
     translations: userTranslations,
@@ -92,6 +101,7 @@ function zudoDoc(user = {}) {
     ...settingsOverrides
   } = user;
   const settings = { ...DEFAULT_SETTINGS, ...settingsOverrides };
+  assertNoCommaInVersionSlugs(settings.versions);
   const fragment = zudoDocPreset({
     settings,
     buildDocsSchema: userBuildDocsSchema ?? (() => defaultBuildDocsSchema({
@@ -111,6 +121,7 @@ function zudoDoc(user = {}) {
     base: settings.base,
     ...adapter ? { adapter } : {},
     ...bundle ? { bundle } : {},
+    ...strictContentBridge !== void 0 ? { strictContentBridge } : {},
     // ── Preset-owned fields (collections, plugins, markdown, …) ──────────
     ...fragment,
     // The preset's `markdown.features` intentionally uses the loose Record

package/dist/content.css

@@ -187,6 +187,7 @@
   color: var(--color-code-fg);
   border-radius: var(--radius-DEFAULT);
   padding: 2px var(--spacing-hsp-xs);
+  overflow-wrap: anywhere;
 }
 
 /* ── Code blocks (pre) ── */

package/dist/desktop-toc-toggle-island/index.d.ts

@@ -0,0 +1,7 @@
+export declare const TOC_STORAGE_KEY = "zudo-doc-toc-visible";
+export declare function readTocState(): boolean;
+export declare function setTocDataAttribute(isVisible: boolean): void;
+export declare function DesktopTocToggle(): import("preact").JSX.Element;
+export declare namespace DesktopTocToggle {
+    var displayName: string;
+}

package/dist/desktop-toc-toggle-island/index.js

@@ -0,0 +1,64 @@
+"use client";
+import { jsx } from "preact/jsx-runtime";
+import { useState, useEffect, useRef } from "preact/hooks";
+import { ChevronRight, ChevronLeft } from "../icons/index.js";
+import { AFTER_NAVIGATE_EVENT } from "../transitions/index.js";
+const TOC_STORAGE_KEY = "zudo-doc-toc-visible";
+function readTocState() {
+  if (typeof window === "undefined") return true;
+  try {
+    return localStorage.getItem(TOC_STORAGE_KEY) !== "false";
+  } catch {
+    return true;
+  }
+}
+function setTocDataAttribute(isVisible) {
+  if (isVisible) {
+    document.documentElement.removeAttribute("data-toc-hidden");
+  } else {
+    document.documentElement.setAttribute("data-toc-hidden", "");
+  }
+}
+function DesktopTocToggle() {
+  const [visible, setVisible] = useState(true);
+  const hydrated = useRef(false);
+  useEffect(() => {
+    if (!hydrated.current) return;
+    setTocDataAttribute(visible);
+    try {
+      localStorage.setItem(TOC_STORAGE_KEY, String(visible));
+    } catch {
+    }
+  }, [visible]);
+  useEffect(() => {
+    hydrated.current = true;
+    const actual = readTocState();
+    if (actual !== visible) {
+      setVisible(actual);
+    }
+  }, []);
+  useEffect(() => {
+    const handler = () => setTocDataAttribute(readTocState());
+    document.addEventListener(AFTER_NAVIGATE_EVENT, handler);
+    return () => document.removeEventListener(AFTER_NAVIGATE_EVENT, handler);
+  }, []);
+  return /* @__PURE__ */ jsx(
+    "button",
+    {
+      type: "button",
+      onClick: () => setVisible((v) => !v),
+      className: "zd-desktop-toc-toggle hidden xl:flex fixed bottom-vsp-xl z-sidebar items-center justify-center w-[1.5rem] h-[3rem] bg-surface border border-muted border-r-0 rounded-l-DEFAULT text-muted cursor-pointer transition-[right,color] duration-200 ease-in-out hover:text-fg",
+      "aria-label": visible ? "Hide table of contents" : "Show table of contents",
+      "aria-pressed": visible,
+      "data-zfb-transition-persist": "desktop-toc-toggle",
+      children: visible ? /* @__PURE__ */ jsx(ChevronRight, { className: "h-icon-sm w-icon-sm" }) : /* @__PURE__ */ jsx(ChevronLeft, { className: "h-icon-sm w-icon-sm" })
+    }
+  );
+}
+DesktopTocToggle.displayName = "DesktopTocToggle";
+export {
+  DesktopTocToggle,
+  TOC_STORAGE_KEY,
+  readTocState,
+  setTocDataAttribute
+};

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

@@ -47,8 +47,11 @@ export interface DocPageRendererDeps {
     /**
      * Build locale-aware MDX components bag.
      * Host passes `createMdxComponents` (from `pages/_mdx-components.ts`).
+     * `currentVersion` (#3218) threads the active `/v/{version}` slug into the
+     * nav-card wrappers (CategoryNav/CategoryTreeNav/SiteTreeNav) so their hrefs
+     * resolve within the version — undefined on latest/unversioned pages.
      */
-    createMdxComponents: (locale: string) => Record<string, unknown>;
+    createMdxComponents: (locale: string, currentVersion?: string) => Record<string, unknown>;
     /** Translate a UI string key for a locale. */
     t: (key: string, locale: string) => string;
     /**
@@ -86,6 +89,14 @@ export interface DocPageRendererDeps {
         currentPath: string;
         currentVersion?: string;
         versionSwitcher: JSX.Element | undefined;
+        /**
+         * This page's unavailable-version slugs, straight from
+         * `getUnavailableVersions(slug, locale)` (`../version-availability`) —
+         * see `DocPageShellProps.unavailableVersions` (`../doc-page-shell`) for
+         * the full absent/empty/populated contract this rides through to the
+         * emitted `data-doc-unavailable-versions` attribute.
+         */
+        unavailableVersions?: ReadonlySet<string>;
         versionBanner?: "unmaintained" | "unreleased";
         versionBannerLatestUrl?: string;
         versionBannerLabels?: VersionBannerLabels;