@takazudo/zudo-doc 8.0.0 → 8.1.0

package/CHANGELOG.md

@@ -8,6 +8,22 @@ 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

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 5.0.1** family (peer floor **^5.0.1**).
+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/compiled.css

@@ -1864,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.

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/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.js

@@ -174,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 })
             ] })

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);

package/dist/settings-defaults.js

@@ -10,6 +10,7 @@ const DEFAULT_SETTINGS = {
   siteDescription: "",
   logo: "auto",
   favicon: void 0,
+  headerBrand: false,
   base: "/",
   trailingSlash: false,
   home: { wide: false, introMarkdown: "", sitemapHeading: "" },

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,6 +354,14 @@ 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. */

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

@@ -9,6 +9,7 @@ import {
 import {
   INDENT,
   connectorLeft,
+  connectorLabelStart,
   ConnectorLines,
   CategoryLinkIcon
 } from "../tree-nav-shared/index.js";
@@ -24,9 +25,11 @@ import {
 import { formatMonthDay } from "../format-date/index.js";
 import { initialCategoryOpenState, toggleCategoryOpenState } from "./state.js";
 const SITE_BASE_PAD = "clamp(0.5rem, 0.8vw, 1rem)";
+const CONNECTOR_WIDTH_SCALE = 2;
+const CONNECTOR_LABEL_GAP = "var(--spacing-hsp-xs)";
 function padLeft(depth) {
   if (depth === 0) return SITE_BASE_PAD;
-  return `calc(${depth} * ${INDENT} + 1.25rem + 5px)`;
+  return `max(calc(${depth} * ${INDENT} + 1.25rem + 5px), ${connectorLabelStart(depth, CONNECTOR_WIDTH_SCALE, CONNECTOR_LABEL_GAP)})`;
 }
 function reorderTree(tree, order) {
   const map = new Map(tree.map((node) => [node.slug, node]));
@@ -158,7 +161,7 @@ function CategoryNode({
         {
           depth,
           isLast: true,
-          widthScale: 2,
+          widthScale: CONNECTOR_WIDTH_SCALE,
           topPad: "calc(0.15rem + var(--spacing-vsp-xs))"
         }
       ) }),
@@ -167,7 +170,7 @@ function CategoryNode({
         {
           depth,
           isLast: false,
-          widthScale: 2,
+          widthScale: CONNECTOR_WIDTH_SCALE,
           topPad: "calc(0.15rem + var(--spacing-vsp-xs))"
         }
       ) }),
@@ -370,7 +373,7 @@ function LeafNode({
       {
         depth,
         isLast: true,
-        widthScale: 2,
+        widthScale: CONNECTOR_WIDTH_SCALE,
         topPad
       }
     ) }),
@@ -379,7 +382,7 @@ function LeafNode({
       {
         depth,
         isLast: false,
-        widthScale: 2,
+        widthScale: CONNECTOR_WIDTH_SCALE,
         topPad
       }
     ) }),

package/dist/transitions/persisted-focus-settle-bootstrap.d.ts

@@ -0,0 +1,2 @@
+/** Settles a retained persisted focus before the router applies its scroll policy. */
+export declare function buildPersistedFocusSettleBootstrap(): string;

package/dist/transitions/persisted-focus-settle-bootstrap.js

@@ -0,0 +1,22 @@
+import { BEFORE_SWAP_EVENT } from "./page-events.js";
+function buildPersistedFocusSettleBootstrap() {
+  return `(function(){
+if(document.__zdPersistedFocusSettle)return;
+document.__zdPersistedFocusSettle=true;
+document.addEventListener(${JSON.stringify(BEFORE_SWAP_EVENT)},function(ev){
+if(typeof ev.swap!=="function")return;
+var originalSwap=ev.swap;
+var wrapped=function(){
+var active=document.activeElement;
+var retained=!!active&&typeof active.closest==="function"&&!!active.closest("[data-zfb-transition-persist]");
+var result=originalSwap.apply(this,arguments);
+if(retained&&active.isConnected&&document.activeElement===active)void document.documentElement.offsetHeight;
+return result;
+};
+try{ev.swap=wrapped;}catch(e){}
+});
+})();`;
+}
+export {
+  buildPersistedFocusSettleBootstrap
+};

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

@@ -4,6 +4,8 @@ export declare const CONNECTOR_OFFSET = "clamp(0.2rem, 0.3vw, 0.5rem)";
 export declare const CONNECTOR_WIDTH = "clamp(0.4rem, 0.6vw, 1rem)";
 export declare const BASE_PAD = "clamp(0.4rem, 0.8vw, 1.3rem)";
 export declare function connectorLeft(depth: number): string;
+/** Left edge a label needs so it starts `gap` after the horizontal connector's endpoint. */
+export declare function connectorLabelStart(depth: number, widthScale: number, gap: string): string;
 export declare function CategoryLinkIcon({ class: className }: {
     class?: string;
 }): import("@takazudo/zfb").Description;

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

@@ -6,6 +6,12 @@ const BASE_PAD = "clamp(0.4rem, 0.8vw, 1.3rem)";
 function connectorLeft(depth) {
   return `calc(${depth} * ${INDENT} + ${CONNECTOR_OFFSET})`;
 }
+function connectorWidth(widthScale) {
+  return widthScale === 1 ? CONNECTOR_WIDTH : `calc(${CONNECTOR_WIDTH} * ${widthScale})`;
+}
+function connectorLabelStart(depth, widthScale, gap) {
+  return `calc(${connectorLeft(depth)} + ${connectorWidth(widthScale)} + ${gap})`;
+}
 const CATEGORY_LINK_PATH = "M5.746 5.74 0 11.49l20.987 20.96C34.126 45.572 41.963 53.45 41.948 53.523c-.012.062-9.456 9.544-20.986 21.07L0 95.55l5.714 5.715c3.142 3.143 5.748 5.715 5.79 5.715s2.63-2.563 5.75-5.696l17.939-18.001c21.867-21.94 29.443-29.599 29.443-29.768 0-.114-.665-.804-5.084-5.275C51.872 40.47 11.71.125 11.565.036 11.525.01 8.906 2.578 5.746 5.74m38.345-.066c-3.132 3.13-5.696 5.71-5.696 5.732-.001.022 2.16 2.185 4.8 4.807 2.641 2.623 8.382 8.338 12.758 12.702 15.38 15.337 23.763 23.641 24.314 24.086.19.153.346.336.346.405 0 .07-1.738 1.847-3.887 3.976a17515 17515 0 0 0-20.35 20.264 19555 19555 0 0 1-17.223 17.158c-.416.409-.757.77-.757.8 0 .083 11.415 11.485 11.457 11.445.235-.22 53.542-53.528 53.542-53.543C103.395 53.472 49.891.02 49.837 0c-.028-.01-2.613 2.543-5.746 5.674";
 function CategoryLinkIcon({ class: className }) {
   return /* @__PURE__ */ jsx(
@@ -27,7 +33,7 @@ function ConnectorLines({
 }) {
   if (depth === 0) return null;
   const left = connectorLeft(depth);
-  const width = widthScale === 1 ? CONNECTOR_WIDTH : `calc(${CONNECTOR_WIDTH} * ${widthScale})`;
+  const width = connectorWidth(widthScale);
   const firstLineMid = `calc(${topPad} + 0.5lh)`;
   return /* @__PURE__ */ jsxs(Fragment, { children: [
     /* @__PURE__ */ jsx(
@@ -61,5 +67,6 @@ export {
   CategoryLinkIcon,
   ConnectorLines,
   INDENT,
+  connectorLabelStart,
   connectorLeft
 };

package/eject/header/header.tsx

@@ -60,6 +60,7 @@ import type {
   Locale,
 } from "./types.js";
 import { GitHub as GitHubIcon } from "../icons/index.js";
+import type { HeaderBrandConfig } from "../settings.js";
 
 /**
  * Boundary helpers the host injects into `<Header>`. These are the URL
@@ -168,6 +169,15 @@ export interface HeaderProps {
   /** 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[];
 
@@ -265,6 +275,7 @@ export function Header(props: HeaderProps): JSX.Element {
     search,
     persistKey,
     siteName,
+    headerBrand,
     headerNav,
     headerRightItems,
     headerRightComponents,
@@ -289,6 +300,16 @@ export function Header(props: HeaderProps): JSX.Element {
   const matchPath = pathForMatch(pathWithoutVersion, lang, i18n.defaultLocale);
 
   const activeNavPath = computeActiveNavPath(headerNav, matchPath);
+  // Direct `<Header>` consumers and raw route payloads bypass the config-time
+  // `assertValidHeaderBrand`, so a malformed value degrades to "no icon".
+  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) => ({
@@ -397,7 +418,17 @@ export function Header(props: HeaderProps): JSX.Element {
         class="min-w-0 truncate text-title font-bold text-fg hover:underline focus:underline"
         title={siteName}
         data-header-logo
+        data-header-brand={brandIconUrl !== null ? true : undefined}
       >
+        {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.
+          <span
+            aria-hidden="true"
+            data-header-brand-icon
+            style={{ "--zd-header-brand-icon": cssUrl(brandIconUrl) }}
+          />
+        )}
         {siteName}
       </a>
 
@@ -908,3 +939,12 @@ function renderRightItem(
 
   return null;
 }
+
+/**
+ * Serialize a URL as a quoted CSS `url()` token so paths with whitespace,
+ * parentheses or quotes survive inside the custom property. Kept local to
+ * this module because the header is ejectable (see `eject/index.ts`).
+ */
+function cssUrl(url: string): string {
+  return `url("${url.replace(/[\\"]/g, "\\$&").replace(/[\n\r\f]/g, "\\a ")}")`;
+}

package/eject/site-tree-nav-island/index.tsx

@@ -12,6 +12,7 @@ import type { ResolvedDateFormats } from "../settings.js";
 import {
   INDENT,
   connectorLeft,
+  connectorLabelStart,
   ConnectorLines,
   CategoryLinkIcon,
 } from "../tree-nav-shared/index.js";
@@ -30,9 +31,15 @@ import { initialCategoryOpenState, toggleCategoryOpenState } from "./state.js";
 // site-tree-nav uses wider padding than the narrow sidebar
 const SITE_BASE_PAD = "clamp(0.5rem, 0.8vw, 1rem)";
 
+// The homepage draws its connectors at twice the sidebar width, so on wide
+// viewports the branch endpoint passes the fixed label indent. The label starts
+// at whichever is further right: that indent, or the endpoint plus a gap.
+const CONNECTOR_WIDTH_SCALE = 2;
+const CONNECTOR_LABEL_GAP = "var(--spacing-hsp-xs)";
+
 function padLeft(depth: number): string {
   if (depth === 0) return SITE_BASE_PAD;
-  return `calc(${depth} * ${INDENT} + 1.25rem + 5px)`;
+  return `max(calc(${depth} * ${INDENT} + 1.25rem + 5px), ${connectorLabelStart(depth, CONNECTOR_WIDTH_SCALE, CONNECTOR_LABEL_GAP)})`;
 }
 
 function reorderTree(tree: SidebarNavNode[], order: string[]): SidebarNavNode[] {
@@ -223,7 +230,7 @@ function CategoryNode({
             <ConnectorLines
               depth={depth}
               isLast={true}
-              widthScale={2}
+              widthScale={CONNECTOR_WIDTH_SCALE}
               topPad="calc(0.15rem + var(--spacing-vsp-xs))"
             />
           )}
@@ -233,7 +240,7 @@ function CategoryNode({
             <ConnectorLines
               depth={depth}
               isLast={false}
-              widthScale={2}
+              widthScale={CONNECTOR_WIDTH_SCALE}
               topPad="calc(0.15rem + var(--spacing-vsp-xs))"
             />
           )}
@@ -495,7 +502,7 @@ function LeafNode({
                 <ConnectorLines
                   depth={depth}
                   isLast={true}
-                  widthScale={2}
+                  widthScale={CONNECTOR_WIDTH_SCALE}
                   topPad={topPad}
                 />
               )}
@@ -505,7 +512,7 @@ function LeafNode({
                 <ConnectorLines
                   depth={depth}
                   isLast={false}
-                  widthScale={2}
+                  widthScale={CONNECTOR_WIDTH_SCALE}
                   topPad={topPad}
                 />
               )}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@takazudo/zudo-doc",
-  "version": "8.0.0",
+  "version": "8.1.0",
   "type": "module",
   "description": "zudo-doc framework primitives layer that sits on top of zfb's engine — sidebar, theme, TOC, breadcrumb, layouts, head injection, View Transitions, SSR-skip wrappers (per ADR-003).",
   "license": "MIT",
@@ -736,9 +736,9 @@
   "peerDependencies": {
     "@modelcontextprotocol/sdk": "1.32.2",
     "@takazudo/zdtp": "^0.5.2 || ^0.6.0 || ^0.7.0 || ^0.8.0",
-    "@takazudo/zfb": "^5.0.1",
-    "@takazudo/zfb-md-wasm": "^5.0.1",
-    "@takazudo/zfb-runtime": "^5.0.1",
+    "@takazudo/zfb": "^5.1.2",
+    "@takazudo/zfb-md-wasm": "^5.1.2",
+    "@takazudo/zfb-runtime": "^5.1.2",
     "@takazudo/zudo-doc-history-server": "^8.0.0",
     "diff": "^8.0.0",
     "katex": "^0.18.2 || ^0.19.0",
@@ -779,9 +779,9 @@
   "devDependencies": {
     "@modelcontextprotocol/sdk": "1.32.2",
     "@takazudo/mdx-formatter": "1.3.0",
-    "@takazudo/zfb": "5.0.1",
-    "@takazudo/zfb-md-wasm": "5.0.1",
-    "@takazudo/zfb-runtime": "5.0.1",
+    "@takazudo/zfb": "5.1.2",
+    "@takazudo/zfb-md-wasm": "5.1.2",
+    "@takazudo/zfb-runtime": "5.1.2",
     "@types/fs-extra": "^11.0.4",
     "@types/minimist": "^1.2.5",
     "@types/node": "^25.3.5",
@@ -791,7 +791,7 @@
     "typescript": "^5.0.0",
     "vitest": "^4.1.0",
     "zod": "^4.3.6",
-    "@takazudo/zudo-doc-history-server": "8.0.0"
+    "@takazudo/zudo-doc-history-server": "8.1.0"
   },
   "scripts": {
     "gen:search-widget-script": "node scripts/gen-search-widget-script.mjs",