@takazudo/zudo-doc 7.1.0 → 8.1.0

package/CHANGELOG.md

@@ -8,6 +8,44 @@ The format is based on Keep a Changelog, and release notes are generated from th
 
 No unreleased changes.
 
+## [8.1.0] - 2026-10-25
+
+### Features
+
+- Add the opt-in `headerBrand` setting (`false | { icon: string }`, default `false`): a decorative square icon painted with the text colour (CSS mask) before the site name in the header. `/`-prefixed paths receive the site `base` once, other URLs are used as-is, and an empty or missing `icon` (or `true`) throws at config resolution. The site name stays the link's accessible name, long names still ellipsize, and theme-pack leading emblems are hidden while an icon is set. (fb3358ca)
+- Add a `data-zd-site-name` attribute to the home hero `<h1>` as a styling hook for the site name. (fb3358ca)
+
+### Bug Fixes
+
+- With dynamic page transitions enabled, navigating from a footer link (or any focused link in persisted chrome) now finishes at the top of the destination page on current Chromium builds instead of staying near the footer. A package-owned inline head script settles the browser's queued focus reveal after the persisted DOM move and before the router applies its top, hash or history scroll. Focus, persistence, transitions and scroll restoration are unchanged. Sites that pin inline-script hashes in a Content Security Policy need to add the new script's hash. (524a440f)
+- In `SiteTreeNav`, labels now always start a small gap after the end of their dashed branch. On wide viewports the double-width homepage branches used to run into the label text. (3e6e720f)
+
+### Other Changes
+
+- Requires zfb 5.1.2: the `@takazudo/zfb`, `zfb-runtime` and `zfb-md-wasm` peer floors move from `^5.0.1` to `^5.1.2`. zfb 5.1.0 adds an islands build guard: the build now fails if an emitted islands chunk imports the islands entry, because that import would 404 in production. zfb 5.1.1 is a fix release for Windows hosts (bare-package subpath aliases and `pnpm.cmd` spawning) and for projects built from a symlinked path. zfb 5.1.2 ships rebuilt native engine and WASM binaries with no change to the JavaScript API. Chunking is otherwise unchanged. Upgrade the zfb family (and `zfb-adapter-cloudflare` when used) to 5.1.2 together with this release. (6eef9416, 44d7684b)
+
+## [8.0.0] - 2026-10-24
+
+### Breaking Changes
+
+- Remove the `@takazudo/zudo-doc/plugins/optional-peers` export. Remove any explicit registration of that workaround plugin; ZFB now handles rejection-handled optional imports directly.
+- Require ZFB 5.0.1 or later in the 5.x line. Upgrade the ZFB engine, runtime, and Markdown WASM packages together. When using document history, upgrade `@takazudo/zudo-doc-history-server` to 8.x as well. Node.js 24 remains the minimum.
+
+### Features
+
+- Add `siteTreeNavInitiallyCollapsed` to start exact nested category slugs collapsed in home-page and MDX site trees while preserving links and toggles. (fb4a6e3cf)
+
+### Bug Fixes
+
+- Adopt ZFB 5.0.1 to fix lazy island chunks requesting an unpublished `islands.js` asset.
+- Restore prose spacing inside tab panels. (5c2f52b92)
+- Clarify adjacent heading spacing and heading hierarchy across theme packs. (2969bd803)
+
+### Other Changes
+
+- Accept Node.js 24 or later without an upper version cap. Node 24 LTS remains the CI-verified line. (d5336a24b)
+- Update the MCP SDK to 1.32.2.
+
 ## [7.1.0] - 2026-10-23
 
 ### Bug Fixes

package/README.md

@@ -109,7 +109,7 @@ If your project renders **semi-trusted or user-submitted** HTML in a preview, ov
 
 **6.0.0** is the coordinated major release of `@takazudo/zudo-doc`,
 `@takazudo/zudo-doc-history-server` and `create-zudo-doc`. The current workspace
-targets the published **zfb 4.7.0** family (peer floor **^4.7.0**).
+targets the published **zfb 5.1.2** family (peer floor **^5.1.2**).
 [Upstream #4097](https://github.com/Takazudo/zudo-front-builder/issues/4097) is
 resolved; its strict published 4.3.1 consumer control passed 3/3 with no skips or
 retries in the [source-bound verification](../../docs/findings/zfb-4.3.1/verification.md).

package/dist/chrome/derive.js

@@ -322,6 +322,7 @@ function deriveMdxComponents(ctx) {
     getCategoryOrder: ctx.getCategoryOrder,
     versionedDocsUrl: ctx.versionedDocsUrl,
     categoryIgnore: ctx.settings.siteTreeNavIgnore,
+    initiallyCollapsedCategorySlugs: ctx.settings.siteTreeNavInitiallyCollapsed,
     dateFormat: ctx.settings.dateFormat
   });
   const NoteTrayIndexWrapper = createNoteTrayIndexWrapper({

package/dist/compiled.css

@@ -630,11 +630,15 @@ body {
 }
 
 @layer zd-flow {
-  .zd-content > :where(* + *) {
+  .zd-content > :where(* + *), .zd-content :where(.tab-panel) > :where(* + *) {
     margin-top: var(--flow-space, var(--spacing-vsp-md));
   }
 }
 
+.zd-content :where(.tab-panel) {
+  --flow-space: var(--spacing-vsp-md);
+}
+
 .zd-content :where(h2) {
   --flow-space: var(--spacing-vsp-2xl);
 }
@@ -658,11 +662,15 @@ body {
   --flow-space: var(--spacing-vsp-xs);
 }
 
+.zd-content :where(h2) + :where(h3) {
+  --flow-space: var(--spacing-vsp-md);
+}
+
 .zd-content :where(h2, h3, h4, h5, h6) + :where(:not(h2, h3, h4, h5, h6)) {
   --flow-space: var(--spacing-vsp-xs);
 }
 
-.zd-content > :first-child {
+.zd-content > :first-child, .zd-content :where(.tab-panel) > :first-child {
   margin-top: 0;
 }
 
@@ -1856,6 +1864,21 @@ nav[data-zd-toc], div[data-zd-mobile-toc] {
   font-family: var(--zdc-toc-font, var(--zdc-chrome-font, var(--font-sans)));
 }
 
+[data-header-brand-icon] {
+  display: inline-block;
+  width: 1.1em;
+  height: 1.1em;
+  vertical-align: -.2em;
+  margin-inline-end: var(--spacing-hsp-sm);
+  background-color: currentColor;
+  -webkit-mask: var(--zd-header-brand-icon) center/contain no-repeat;
+  mask: var(--zd-header-brand-icon) center/contain no-repeat;
+}
+
+html[data-theme-pack] [data-header-logo][data-header-brand]:before {
+  content: none;
+}
+
 button[data-zd-pending] {
   opacity: .7;
   pointer-events: none;

package/dist/config-assertions/index.d.ts

@@ -55,6 +55,19 @@ export interface EmptyStringFaviconOrLogoSubject {
  * object is not an empty string).
  */
 export declare function assertNoEmptyStringFaviconOrLogo(settings: EmptyStringFaviconOrLogoSubject): void;
+/** Structural subset of `Settings` {@link assertValidHeaderBrand} reads. */
+export interface HeaderBrandSubject {
+    headerBrand?: unknown;
+}
+/**
+ * Validate `headerBrand`: `undefined`, `false`, or `{ icon: <non-empty string> }`.
+ *
+ * The value is typed `false | HeaderBrandConfig`, but JavaScript callers and
+ * casted values can still pass `true`, a bare string, an array, or an object
+ * whose `icon` is missing/empty — each of which would render a broken mask in
+ * every page header. Fail loudly at config resolution, naming the field.
+ */
+export declare function assertValidHeaderBrand(settings: HeaderBrandSubject): void;
 /** Structural subset of `Settings` the zdtp-bundling helpers read. */
 export interface ZdtpBundlingSubject {
     designTokenPanel?: boolean;

package/dist/config-assertions/index.js

@@ -32,6 +32,30 @@ function assertNoEmptyStringFaviconOrLogo(settings) {
     }
   }
 }
+function assertValidHeaderBrand(settings) {
+  const value = settings.headerBrand;
+  if (value === void 0 || value === false) return;
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new TypeError(
+      `Invalid headerBrand ${describeValue(value)}: pass false (or omit it) for no icon, or an object { icon: "/img/icon.svg" }.`
+    );
+  }
+  const icon = value.icon;
+  if (typeof icon !== "string" || icon === "") {
+    throw new TypeError(
+      `Invalid headerBrand.icon ${describeValue(icon)}: must be a non-empty string (a "/"-prefixed path, a data: URL, or an absolute URL).`
+    );
+  }
+}
+function describeValue(value) {
+  if (value === void 0) return "undefined";
+  if (Array.isArray(value)) return "(array)";
+  try {
+    return JSON.stringify(value) ?? String(value);
+  } catch {
+    return String(value);
+  }
+}
 function resolvesBundleZdtp(settings) {
   return settings.bundleZdtp ?? settings.designTokenPanel === true;
 }
@@ -92,6 +116,7 @@ function warnAmbiguousDropdownCategoryMatch(headerNav, logger = console) {
 export {
   assertAgentDocsConsistent,
   assertNoEmptyStringFaviconOrLogo,
+  assertValidHeaderBrand,
   assertValidSearchMaxBodyLength,
   assertZdtpBundlingConsistent,
   resolvesBundleZdtp,

package/dist/config.d.ts

@@ -70,7 +70,7 @@ import type { ZfbConfig, BundleConfig, WindConfig } from "@takazudo/zfb/config";
 import type { ZodType } from "zod";
 import type { DirectiveVocabulary, PresetTranslations, PresetTagVocabularyEntry } from "./preset.js";
 import type { ColorScheme } from "./color-scheme-utils.js";
-import type { Settings, ColorModeConfig, LocaleConfig, MetaTagsConfig, SiteHeadConfig, TagPlacement, TagGovernanceMode, VersionConfig, FooterConfig, HeaderNavItem, HeaderRightItem, HomeConfig, AssetViewerIndexingConfig, FrontmatterPreviewConfig, BodyFootUtilAreaConfig, HtmlPreviewConfig, FaviconConfig, DateFormatSetting } from "./settings.js";
+import type { Settings, ColorModeConfig, LocaleConfig, MetaTagsConfig, SiteHeadConfig, TagPlacement, TagGovernanceMode, VersionConfig, FooterConfig, HeaderNavItem, HeaderRightItem, HomeConfig, AssetViewerIndexingConfig, FrontmatterPreviewConfig, BodyFootUtilAreaConfig, HtmlPreviewConfig, FaviconConfig, HeaderBrandConfig, DateFormatSetting } from "./settings.js";
 /** The `settings.claudeResources` block (or `false` when disabled). */
 type ClaudeResourcesConfig = {
     claudeDir: string;
@@ -132,6 +132,17 @@ export interface ZudoDocConfig {
      * @default undefined
      */
     favicon?: string | FaviconConfig | false;
+    /**
+     * Header brand icon rendered before the site name in the header logo
+     * anchor, as a decorative `currentColor` CSS mask (`aria-hidden`; the
+     * anchor's accessible name stays `siteName`). `false` renders the site name
+     * alone. A `HeaderBrandConfig` (`{ icon }`) paints `icon`: a value starting
+     * with `/` is prefixed with `base`, anything else (`data:`, `https://…`) is
+     * used verbatim. `true`, arrays, other non-objects, and a missing,
+     * non-string or empty `icon` throw a `TypeError` at config resolution.
+     * @default false
+     */
+    headerBrand?: false | HeaderBrandConfig;
     /**
      * Public URL sub-path prefix mounted in front of every absolute asset URL
      * (e.g. `"/pj/my-site/"`). `"/"` = root-mounted.
@@ -158,6 +169,15 @@ export interface ZudoDocConfig {
      * @default []
      */
     siteTreeNavIgnore?: string[];
+    /**
+     * Exact full `node.slug` values of categories that start collapsed at any
+     * depth in package-owned home pages and `<SiteTreeNav />` / `<SiteTreeNavDemo />`
+     * MDX tags. Use slugs such as `"zudo-wind/utilities"`, without `/docs`, a
+     * locale prefix, or leading/trailing slashes. Visitors can toggle them normally.
+     * Does not affect sidebar expansion.
+     * @default []
+     */
+    siteTreeNavInitiallyCollapsed?: string[];
     /**
      * Top-level category slugs moved OUT of the package-owned home-page category
      * grid on `/` and locale homes and rendered instead as one row of small

package/dist/config.js

@@ -6,6 +6,7 @@ import { defaultColorSchemes } from "./color-schemes-defaults/index.js";
 import { assertNoCommaInVersionSlugs } from "./version-availability/index.js";
 import {
   assertNoEmptyStringFaviconOrLogo,
+  assertValidHeaderBrand,
   assertZdtpBundlingConsistent,
   assertValidSearchMaxBodyLength,
   assertAgentDocsConsistent
@@ -79,6 +80,7 @@ function zudoDoc(user = {}) {
   );
   assertNoCommaInVersionSlugs(settings.versions);
   assertNoEmptyStringFaviconOrLogo(settings);
+  assertValidHeaderBrand(settings);
   assertZdtpBundlingConsistent(settings);
   assertValidSearchMaxBodyLength(settings.searchMaxBodyLength);
   assertAgentDocsConsistent(settings);

package/dist/content.css

@@ -74,11 +74,17 @@
  * layer-independent, so the per-heading flow gaps are unaffected.
  * See zudolab/zudo-doc#2082 / #2109. */
 @layer zd-flow {
-  .zd-content > :where(* + *) {
+  .zd-content > :where(* + *),
+  .zd-content :where(.tab-panel) > :where(* + *) {
     margin-top: var(--flow-space, var(--spacing-vsp-md));
   }
 }
 
+/* Tabs can inherit a heading-following gap; start a new prose flow inside. */
+.zd-content :where(.tab-panel) {
+  --flow-space: var(--spacing-vsp-md);
+}
+
 /* ── Headings ── */
 
 /* Heading flow-space (structural — consumed by flow spacing system) */
@@ -107,13 +113,18 @@
   --flow-space: var(--spacing-vsp-xs);
 }
 
+.zd-content :where(h2) + :where(h3) {
+  --flow-space: var(--spacing-vsp-md);
+}
+
 /* Content immediately after a heading: tight gap (replaces heading margin-bottom) */
 .zd-content :where(h2, h3, h4, h5, h6) + :where(:not(h2, h3, h4, h5, h6)) {
   --flow-space: var(--spacing-vsp-xs);
 }
 
 /* First child never needs top margin */
-.zd-content > :first-child {
+.zd-content > :first-child,
+.zd-content :where(.tab-panel) > :first-child {
   margin-top: 0;
 }
 

package/dist/doclayout/doc-layout.js

@@ -1,6 +1,7 @@
 import { jsx, jsxs } from "@takazudo/zfb/zudo-react/jsx-runtime";
 import { ClientRouter } from "@takazudo/zfb-runtime";
 import { buildChromeTransitionBootstrap } from "../transitions/chrome-transition-bootstrap.js";
+import { buildPersistedFocusSettleBootstrap } from "../transitions/persisted-focus-settle-bootstrap.js";
 const DESKTOP_SIDEBAR_ID = "desktop-sidebar";
 function DocLayout(props) {
   const {
@@ -71,7 +72,10 @@ function DocLayout(props) {
     );
   }
   if (head !== void 0) headChildren.push(head);
-  if (enableClientRouter !== false) headChildren.push(/* @__PURE__ */ jsx("script", { rawHtml: buildChromeTransitionBootstrap() }));
+  if (enableClientRouter !== false) {
+    headChildren.push(/* @__PURE__ */ jsx("script", { rawHtml: buildChromeTransitionBootstrap() }));
+    headChildren.push(/* @__PURE__ */ jsx("script", { rawHtml: buildPersistedFocusSettleBootstrap() }));
+  }
   return /* @__PURE__ */ jsxs("html", { ...htmlAttrs, children: [
     /* @__PURE__ */ jsx("head", { children: headChildren }),
     /* @__PURE__ */ jsxs("body", { class: "min-h-screen antialiased", children: [

package/dist/features.css

@@ -1026,6 +1026,30 @@ nav[data-zd-toc], div[data-zd-mobile-toc] {
 
 /* END --zdc-* chrome component tokens */
 
+/* ======== Header brand icon (settings.headerBrand) ======== */
+
+/* Decorative icon inside the site-name anchor. Sized in `em` so it follows a
+ * theme pack's logo font-size inside the fixed-height header; painted as a
+ * currentColor mask so it always matches the site-name ink. The anchor stays
+ * a truncating flow box — the icon is an inline-block run-in, not a flex item. */
+[data-header-brand-icon] {
+  display: inline-block;
+  width: 1.1em;
+  height: 1.1em;
+  vertical-align: -0.2em;
+  margin-inline-end: var(--spacing-hsp-sm);
+  background-color: currentColor;
+  -webkit-mask: var(--zd-header-brand-icon) center/contain no-repeat;
+  mask: var(--zd-header-brand-icon) center/contain no-repeat;
+}
+
+/* A brand icon replaces a theme pack's decorative logo emblem rather than
+ * doubling it. Specificity (0,3,2) beats every pack's `[data-header-logo]::before`
+ * rule (0,2,2); `::after` marks are left alone. */
+html[data-theme-pack] [data-header-logo][data-header-brand]::before {
+  content: none;
+}
+
 button[data-zd-pending] {
   opacity: 0.7;
   pointer-events: none;

package/dist/header/header.d.ts

@@ -2,6 +2,7 @@
 import type { Child } from "@takazudo/zfb/zudo-react";
 import type { JSX } from "@takazudo/zfb/zudo-react/jsx-runtime";
 import type { HeaderNavItem, HeaderRightComponentRegistry, HeaderRightItem, Locale } from "./types.js";
+import type { HeaderBrandConfig } from "../settings.js";
 /**
  * Boundary helpers the host injects into `<Header>`. These are the URL
  * builders the legacy header.tsx used to import from `@/utils/base` —
@@ -92,6 +93,14 @@ export interface HeaderProps {
     persistKey: string;
     /** Site-name string shown in the logo anchor (host `settings.siteName`). */
     siteName: string;
+    /**
+     * Optional brand icon rendered before `siteName` inside the logo anchor
+     * (host `settings.headerBrand`). Omitted or `false` renders the anchor
+     * exactly as before. The icon is a decorative `currentColor` CSS mask; an
+     * `icon` starting with `/` goes through `urlHelpers.withBase()`, anything
+     * else is used verbatim.
+     */
+    headerBrand?: false | HeaderBrandConfig;
     /** Header-nav items in render order (host `settings.headerNav`). */
     headerNav: HeaderNavItem[];
     /**

package/dist/header/header.js

@@ -32,6 +32,7 @@ function Header(props) {
     search,
     persistKey,
     siteName,
+    headerBrand,
     headerNav,
     headerRightItems,
     headerRightComponents,
@@ -48,6 +49,8 @@ function Header(props) {
   const pathWithoutVersion = stripCurrentVersionPrefix(pathWithoutBase, currentVersion);
   const matchPath = pathForMatch(pathWithoutVersion, lang, i18n.defaultLocale);
   const activeNavPath = computeActiveNavPath(headerNav, matchPath);
+  const brandIcon = headerBrand && typeof headerBrand.icon === "string" && headerBrand.icon !== "" ? headerBrand.icon : null;
+  const brandIconUrl = brandIcon === null ? null : brandIcon.startsWith("/") && !brandIcon.startsWith("//") ? urlHelpers.withBase(brandIcon) : brandIcon;
   const rightItemDispatch = createRightItemDispatch(headerRightComponents);
   const rightItems = headerRightItems.map((item, i) => ({
     item,
@@ -98,14 +101,27 @@ function Header(props) {
         // (mobile sidebar contents stay accessible to assistive tech
         // even without the toggle island).
         /* @__PURE__ */ jsx(SidebarSlotFallback, { children: sidebarSlot }),
-        /* @__PURE__ */ jsx(
+        /* @__PURE__ */ jsxs(
           "a",
           {
             href: urlHelpers.withBase(isNonDefaultLocale ? `/${lang}/` : "/"),
             class: "min-w-0 truncate text-title font-bold text-fg hover:underline focus:underline",
             title: siteName,
             "data-header-logo": true,
-            children: siteName
+            "data-header-brand": brandIconUrl !== null ? true : void 0,
+            children: [
+              brandIconUrl !== null && // Painted by features.css as a currentColor mask so it follows the
+              // site-name ink; decorative, the anchor's name stays the site name.
+              /* @__PURE__ */ jsx(
+                "span",
+                {
+                  "aria-hidden": "true",
+                  "data-header-brand-icon": true,
+                  style: { "--zd-header-brand-icon": cssUrl(brandIconUrl) }
+                }
+              ),
+              siteName
+            ]
           }
         ),
         /* @__PURE__ */ jsxs(
@@ -486,6 +502,9 @@ function renderRightItem(item, index, ctx, dispatch) {
   }
   return null;
 }
+function cssUrl(url) {
+  return `url("${url.replace(/[\\"]/g, "\\$&").replace(/[\n\r\f]/g, "\\a ")}")`;
+}
 export {
   Header
 };

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

@@ -1,7 +1,7 @@
 /** @jsxRuntime automatic */
 import type { JSX } from "@takazudo/zfb/zudo-react/jsx-runtime";
 import type { ChromeContext } from "../factory-context/index.js";
-import type { Settings } from "../settings.js";
+import type { HeaderBrandConfig, Settings } from "../settings.js";
 import type { SidebarNavNode } from "../sidebar/types.js";
 export interface HeaderWithDefaultsProps {
     /** Active locale; defaults to the configured defaultLocale. */
@@ -44,6 +44,8 @@ export interface HeaderVersionEntry {
 /** Settings subset read by {@link createHeaderWithDefaults}. */
 export interface HeaderWithDefaultsSettings {
     siteName: string;
+    /** Optional header brand icon — forwarded verbatim to `<Header>`. */
+    headerBrand?: false | HeaderBrandConfig;
     /** 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. */

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

@@ -194,6 +194,7 @@ function createHeaderWithDefaults(ctx) {
         languageSwitcher,
         persistKey,
         siteName: settings.siteName,
+        headerBrand: settings.headerBrand,
         headerNav: settings.headerNav,
         headerRightItems,
         headerRightComponents: ctx.hostBindings.headerRightComponents,

package/dist/home-page/index.d.ts

@@ -43,7 +43,7 @@ export interface HomePageViewProps {
     tree: DocNavNode[];
     /** Ordered category prefixes, passed through to `SiteTreeNav`. */
     categoryOrder: string[];
-    /** Root-category slugs that should start collapsed in `SiteTreeNav`. */
+    /** Exact full category slugs at any depth that should start collapsed in `SiteTreeNav`. Overrides `settings.siteTreeNavInitiallyCollapsed`, including when `[]`. */
     initiallyCollapsedCategorySlugs?: string[];
     /** Unique tag count for the current locale — gates the "Tags" section
      *  together with `settings.docTags`. Part of the documented public

package/dist/home-page/index.js

@@ -87,6 +87,7 @@ function createHomePageView(ctx) {
     wide
   }) {
     const prefix = locale === defaultLocale ? "" : `/${locale}`;
+    const effectiveInitiallyCollapsedCategorySlugs = initiallyCollapsedCategorySlugs ?? settings.siteTreeNavInitiallyCollapsed;
     const rawDescription = settings.locales[locale]?.description ?? settings.siteDescription;
     const description = rawDescription?.trim() ? rawDescription : void 0;
     const ctaNav = settings.headerNav[0] ?? null;
@@ -173,7 +174,7 @@ function createHomePageView(ctx) {
               }
             ) : null,
             /* @__PURE__ */ jsxs("div", { class: "zd-home-copy min-w-0 lg:flex-1", children: [
-              /* @__PURE__ */ jsx("h1", { class: "text-heading font-bold mb-vsp-2xs zd-wrap-anywhere", children: settings.siteName }),
+              /* @__PURE__ */ jsx("h1", { class: "text-heading font-bold mb-vsp-2xs zd-wrap-anywhere", "data-zd-site-name": true, children: settings.siteName }),
               /* @__PURE__ */ jsx("p", { class: "text-muted text-small mb-vsp-sm", children: rawDescription }),
               /* @__PURE__ */ jsx("div", { class: "zd-home-links flex flex-wrap items-center justify-center lg:justify-start gap-hsp-md text-small", children: rowContent })
             ] })
@@ -193,7 +194,7 @@ function createHomePageView(ctx) {
                   tree,
                   categoryOrder,
                   categoryIgnore: [...categoryIgnore, ...movedNodes.map((n) => n.slug)],
-                  ...initiallyCollapsedCategorySlugs !== void 0 ? { initiallyCollapsedCategorySlugs } : {},
+                  ...effectiveInitiallyCollapsedCategorySlugs !== void 0 ? { initiallyCollapsedCategorySlugs: effectiveInitiallyCollapsedCategorySlugs } : {},
                   locale,
                   updatedLabel: t("doc.updated", locale),
                   dateFormats: dateFormatsFor(locale)

package/dist/nav-indexing/note-tray-index-parts/index-list.js

@@ -5,12 +5,12 @@ function IndexList(props) {
   const width = rankWidth(props.items);
   return /* @__PURE__ */ jsx("ol", { class: "zd-list-items-no-margin", children: props.items.map((item) => {
     const rowClass = item.href ? "relative -mt-px first:mt-0 border-y border-muted hover:z-local-1 hover:border-accent focus-within:z-local-1 focus-within:border-accent" : "relative -mt-px first:mt-0 border-y border-muted";
-    const rankClass = item.href ? "tabular-nums text-heading leading-none text-muted group-hover:text-fg group-focus-visible:text-fg" : "tabular-nums text-heading leading-none text-muted";
+    const rankClass = item.href ? "whitespace-nowrap tabular-nums text-heading leading-none text-muted group-hover:text-fg group-focus-visible:text-fg" : "whitespace-nowrap tabular-nums text-heading leading-none text-muted";
     const labelClass = item.href ? "font-medium text-fg group-hover:text-accent group-hover:underline group-focus-visible:text-accent group-focus-visible:underline" : "font-medium text-fg";
     const detailClass = item.href ? "mt-vsp-2xs block text-small text-muted group-hover:text-accent group-hover:underline group-focus-visible:text-accent group-focus-visible:underline" : "mt-vsp-2xs block text-small text-muted";
     const dateClass = item.href ? "mt-vsp-2xs block text-caption text-muted group-hover:text-accent group-hover:underline group-focus-visible:text-accent group-focus-visible:underline" : "mt-vsp-2xs block text-caption text-muted";
     const rowContent = /* @__PURE__ */ jsxs(Fragment, { children: [
-      /* @__PURE__ */ jsx("span", { class: rankClass, style: { width: `${width}ch` }, children: item.rank === void 0 ? "" : String(item.rank).padStart(width, "0") }),
+      /* @__PURE__ */ jsx("span", { class: rankClass, style: { "min-width": `${width}ch` }, children: item.rank === void 0 ? "" : String(item.rank).padStart(width, "0") }),
       /* @__PURE__ */ jsxs("span", { class: "min-w-0", children: [
         /* @__PURE__ */ jsx("span", { class: labelClass, children: item.label }),
         item.description && /* @__PURE__ */ jsx("span", { class: detailClass, children: item.description }),

package/dist/preset.d.ts

@@ -36,7 +36,7 @@
 import { z } from "zod";
 import type { DirectiveSpec, ZfbConfig } from "@takazudo/zfb/config";
 import type { ColorScheme } from "./color-scheme-utils.js";
-import type { AssetViewerIndexingConfig, TagVocabularyEntry, FaviconConfig, HomeConfig } from "./settings.js";
+import type { AssetViewerIndexingConfig, TagVocabularyEntry, FaviconConfig, HeaderBrandConfig, HomeConfig } from "./settings.js";
 /** A single locale's content directory (`settings.locales[code]`). */
 export interface PresetLocaleConfig {
     dir: string;
@@ -109,6 +109,9 @@ export interface PresetSettings {
     /** Favicon links. Same rationale as {@link PresetSettings.logo} — carried
      *  only for `assertNoEmptyStringFaviconOrLogo` (#3474). */
     favicon?: string | FaviconConfig | false;
+    /** Header brand icon. Same rationale as {@link PresetSettings.logo} — carried
+     *  only for `assertValidHeaderBrand`; rendering happens in the header. */
+    headerBrand?: false | HeaderBrandConfig;
     /** GitHub repository URL used by asset backlink metadata. */
     githubUrl?: string | false;
     siteUrl: string;

package/dist/preset.js

@@ -2,6 +2,7 @@ import { z } from "zod";
 import { assertNoCommaInVersionSlugs } from "./version-availability/index.js";
 import {
   assertNoEmptyStringFaviconOrLogo,
+  assertValidHeaderBrand,
   assertZdtpBundlingConsistent,
   assertValidSearchMaxBodyLength,
   assertAgentDocsConsistent,
@@ -19,6 +20,7 @@ function zudoDocPreset({
 }) {
   assertNoCommaInVersionSlugs(settings.versions);
   assertNoEmptyStringFaviconOrLogo(settings);
+  assertValidHeaderBrand(settings);
   assertZdtpBundlingConsistent(settings);
   assertValidSearchMaxBodyLength(settings.searchMaxBodyLength);
   assertAgentDocsConsistent(settings);
@@ -130,16 +132,6 @@ function buildMarkdownFeatures(settings, directiveVocabulary) {
     headingIds: { strategy: "hierarchical" }
   };
 }
-function optionalPeerShadows(settings) {
-  const peers = [
-    ["katex", Boolean(settings.math)],
-    ["diff", Boolean(settings.docHistory)]
-  ];
-  return {
-    shadow: peers.filter(([, on]) => !on).map(([name]) => name),
-    shadowIfMissing: peers.filter(([, on]) => on).map(([name]) => name)
-  };
-}
 function buildPlugins(settings, routeContext) {
   const localeArray = Object.entries(settings.locales).map(([code, locale]) => ({
     code,
@@ -347,10 +339,7 @@ function buildPlugins(settings, routeContext) {
     // `design-token-panel-bootstrap` (#4261). Preset-level rather than inside
     // the routes plugin because the bootstrap is reachable from chrome even
     // when packageOwnedRoutes is off.
-    ...resolvesBundleZdtp(settings) ? [] : [{ name: "@takazudo/zudo-doc/plugins/zdtp-loader", options: {} }],
-    // Absent or disabled katex/diff → throwing shadows, so they cannot fail a
-    // Rolldown build (Takazudo/zudo-front-builder#4429).
-    { name: "@takazudo/zudo-doc/plugins/optional-peers", options: optionalPeerShadows(settings) }
+    ...resolvesBundleZdtp(settings) ? [] : [{ name: "@takazudo/zudo-doc/plugins/zdtp-loader", options: {} }]
   ];
 }
 export {

package/dist/settings-defaults.js

@@ -10,10 +10,12 @@ const DEFAULT_SETTINGS = {
   siteDescription: "",
   logo: "auto",
   favicon: void 0,
+  headerBrand: false,
   base: "/",
   trailingSlash: false,
   home: { wide: false, introMarkdown: "", sitemapHeading: "" },
   siteTreeNavIgnore: [],
+  siteTreeNavInitiallyCollapsed: [],
   siteTreeNavSecondary: [],
   minifyHtml: true,
   docsDir: "src/content/docs",

package/dist/settings.d.ts

@@ -260,6 +260,19 @@ export interface FaviconConfig {
     png16?: string;
     ico?: string;
 }
+/**
+ * Opt-in header brand icon rendered before the site name in the header logo
+ * anchor. The icon is painted as a `currentColor` CSS mask, so it follows the
+ * site-name ink in every color scheme and theme pack; it is decorative
+ * (`aria-hidden`) and the anchor's accessible name stays the site name.
+ *
+ * `icon` values starting with `/` are passed through `withBase()`; anything
+ * else (`data:`, `https://…`) is used verbatim. The value must be a non-empty
+ * string — anything else throws a `TypeError` at config resolution.
+ */
+export interface HeaderBrandConfig {
+    icon: string;
+}
 /**
  * Site-wide custom `<head>` extras injected into every page via
  * {@link HeadWithDefaults}. All fields are JSON-serializable (no VNodes or
@@ -341,12 +354,22 @@ export interface Settings {
      * resolves to the current document — pass `false` or omit instead (#3471).
      */
     favicon?: string | FaviconConfig | false;
+    /**
+     * Header brand icon shown before the site name in the header logo anchor.
+     * Omitted or `false` (the default) renders the site name alone, exactly as
+     * before; a {@link HeaderBrandConfig} renders its `icon` as a decorative
+     * `currentColor` mask. Invalid values (`true`, a non-object, an array, a
+     * missing/non-string/empty `icon`) throw a `TypeError` at config resolution.
+     */
+    headerBrand?: false | HeaderBrandConfig;
     base: string;
     trailingSlash: boolean;
     /** Package-owned home-page layout. Narrow when omitted. */
     home?: HomeConfig;
     /** Top-level category slugs hidden from the package home-page grid and the `<SiteTreeNav />` MDX tag. Nothing hidden when omitted. */
     siteTreeNavIgnore?: string[];
+    /** Exact full category slugs to start collapsed at any depth in home and MDX SiteTreeNav. Defaults to `[]`. */
+    siteTreeNavInitiallyCollapsed?: string[];
     /** Top-level category slugs moved from the package home-page grid into the secondary link row under it. Nothing moved when omitted. */
     siteTreeNavSecondary?: string[];
     /** Minify production HTML output from `zfb build`. Defaults to `true` when omitted. */

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

@@ -82,6 +82,8 @@ export interface SiteTreeNavDeps {
      * package chrome passes `settings.siteTreeNavIgnore`.
      */
     categoryIgnore?: string[];
+    /** Exact full category slugs to start collapsed at any depth. Optional for existing factory callers. */
+    initiallyCollapsedCategorySlugs?: string[];
     /**
      * The raw `dateFormat` setting (`ctx.settings.dateFormat`). Resolved to
      * per-role patterns for the render locale and forwarded to the island as

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

@@ -13,6 +13,7 @@ function createSiteTreeNavWrapper(deps) {
     getCategoryOrder,
     versionedDocsUrl,
     categoryIgnore,
+    initiallyCollapsedCategorySlugs,
     dateFormat
   } = deps;
   function SiteTreeNavWrapper({
@@ -43,6 +44,7 @@ function createSiteTreeNavWrapper(deps) {
       tree,
       categoryOrder,
       ...categoryIgnore !== void 0 ? { categoryIgnore } : {},
+      ...initiallyCollapsedCategorySlugs !== void 0 ? { initiallyCollapsedCategorySlugs } : {},
       ...ariaLabel !== void 0 ? { ariaLabel } : {},
       locale,
       dateFormats: resolveDateFormats(dateFormat, locale)

package/dist/site-tree-nav/normalize-island-props.d.ts

@@ -4,6 +4,7 @@ export interface SiteTreeNavIslandProps {
     tree: SidebarNavNode[];
     categoryOrder: string[];
     categoryIgnore?: string[];
+    initiallyCollapsedCategorySlugs?: string[];
     ariaLabel?: string;
     locale: string;
     dateFormats: ResolvedDateFormats;