@takazudo/zudo-doc 8.0.0 → 8.1.1

package/CHANGELOG.md

@@ -8,6 +8,46 @@ The format is based on Keep a Changelog, and release notes are generated from th
 
 No unreleased changes.
 
+## [8.1.1] - 2026-10-26
+
+### Bug Fixes
+
+- Search-index bodies, llms.txt descriptions and agent-export fallback descriptions now read as plain prose.
+  - Inline code keeps its text and only the backticks are dropped. Before, `` `pnpm approve-builds` `` was deleted, leaving fragments like "by default ()".
+  - Whole-line directive fences are removed and their label or title text is kept. This covers `:::warning[Title]`, `:::note Title`, `:::name{attrs}`, nested `::::` and bare closing `:::`. (9d0bffb5, 64cae6a6)
+- Sites that don't use math and don't install the optional `katex` peer no longer get a Rolldown `UNRESOLVED_IMPORT 'katex'` warning on every build.
+  - math-block now loads KaTeX through the package-owned `@takazudo/zudo-doc/katex-loader` subpath. With `math` off, the preset replaces that subpath with a stub.
+  - Bare `katex` imports in your own code are untouched.
+  - `` now requires `math: true`, as already documented. With `math` off it reports the missing-katex error even when `katex` happens to be installed. (82c24ea5, 64cae6a6)
+- Sites with `docHistory` off that don't install the optional `diff` peer no longer get an `UNRESOLVED_IMPORT 'diff'` warning.
+  - The doc-history Compare view loads `diff` through the package-owned `@takazudo/zudo-doc/diff-loader` subpath. With `docHistory` off, the preset replaces that subpath with a stub.
+  - The dates-only mode (`docHistoryUi: false`) keeps the real loader. (6e6434ca)
+- Some row descendants now follow their own row's hover and focus-visible accent, while keeping their resting colors and the inverted current-item style. This covers:
+  - numbered index ranks
+  - linked note-tray dates (index, compact and wide card stamps)
+  - sidebar tray and site-tree note-tray ranks and dates
+  - asset-tree folder and file icons, names and metadata (4c271316, 0efa5cbf)
+
+### Other Changes
+
+- Requires zfb 5.1.3: the `@takazudo/zfb`, `zfb-runtime` and `zfb-md-wasm` peer floors move from `^5.1.2` to `^5.1.3`. zfb 5.1.3 rebuilds the native engine and WASM binaries; the JavaScript API is unchanged. Update the zfb family (and `zfb-adapter-cloudflare` when used) to 5.1.3 together with this release. (62648582)
+
+## [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.3** family (peer floor **^5.1.3**).
 [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).
@@ -126,7 +126,7 @@ are feature-dependent. Package defaults for `agentExport`, `mcp`, and `llmsTxt`
 are all `false`. The create-zudo-doc initializer enables `llmsTxt` by default;
 agent export and MCP remain opt-in.
 
-For the panel, the installed **zdtp 0.8.6** manifest carries **Preact ^10.29.1** as
+For the panel, the installed **zdtp 0.8.7** manifest carries **Preact ^10.29.1** as
 its own dependency (it was a peer through 0.8.5) and exports `./styles.css` (also `./styles`) to `dist/zdtp.css`. Its internal
 Tailwind browser dependency and Preact subtree are isolated from host JSX.
 Install `@takazudo/zdtp` and import `@takazudo/zdtp/styles.css` when enabling it.

package/dist/asset-index-page/body.js

@@ -48,15 +48,15 @@ function iconFor(asset) {
 function AssetTree({ node, base, routePrefix, locale, fileCountLabel, fileCountSingleLabel, linesLabel, root = false }) {
   return /* @__PURE__ */ jsxs("ul", { "data-zd-asset-tree": root ? true : void 0, children: [
     node.dirs.map((dir) => /* @__PURE__ */ jsx("li", { children: /* @__PURE__ */ jsxs("details", { open: true, children: [
-      /* @__PURE__ */ jsxs("summary", { class: "flex cursor-pointer items-center gap-hsp-xs rounded px-hsp-sm py-vsp-3xs text-small hover:bg-accent/10 focus-visible:bg-accent/10", children: [
-        /* @__PURE__ */ jsx(ChevronRight, { class: "h-icon-xs w-icon-xs shrink-0 text-muted transition-transform" }),
-        /* @__PURE__ */ jsx(Folder, { class: "h-icon-sm w-icon-sm shrink-0 text-muted" }),
-        /* @__PURE__ */ jsx(FolderOpen, { class: "h-icon-sm w-icon-sm shrink-0 text-muted" }),
-        /* @__PURE__ */ jsxs("span", { class: "min-w-0 truncate font-mono text-fg", children: [
+      /* @__PURE__ */ jsxs("summary", { class: "group flex cursor-pointer items-center gap-hsp-xs rounded px-hsp-sm py-vsp-3xs text-small hover:bg-accent/10 focus-visible:bg-accent/10", children: [
+        /* @__PURE__ */ jsx(ChevronRight, { class: "h-icon-xs w-icon-xs shrink-0 text-muted transition-transform group-hover:text-accent group-focus-visible:text-accent" }),
+        /* @__PURE__ */ jsx(Folder, { class: "h-icon-sm w-icon-sm shrink-0 text-muted group-hover:text-accent group-focus-visible:text-accent" }),
+        /* @__PURE__ */ jsx(FolderOpen, { class: "h-icon-sm w-icon-sm shrink-0 text-muted group-hover:text-accent group-focus-visible:text-accent" }),
+        /* @__PURE__ */ jsxs("span", { class: "min-w-0 truncate font-mono text-fg group-hover:text-accent group-focus-visible:text-accent", children: [
           dir.name,
           "/"
         ] }),
-        /* @__PURE__ */ jsxs("span", { class: "ml-auto hidden whitespace-nowrap pl-hsp-lg text-caption text-muted sm:block", children: [
+        /* @__PURE__ */ jsxs("span", { class: "ml-auto hidden whitespace-nowrap pl-hsp-lg text-caption text-muted sm:block group-hover:text-accent group-focus-visible:text-accent", children: [
           countLabel(dir.fileCount, fileCountLabel, fileCountSingleLabel),
           " \xB7 ",
           formatAssetBytes(dir.bytes)
@@ -68,10 +68,10 @@ function AssetTree({ node, base, routePrefix, locale, fileCountLabel, fileCountS
       const Icon = iconFor(asset);
       const facet = facetLabel(asset, asset.lines !== void 0 ? linesLabel.replace("{count}", String(asset.lines)) : void 0);
       const meta = [kindLabel(asset), facet, formatAssetBytes(asset.bytes)].filter(Boolean).join(" \xB7 ");
-      return /* @__PURE__ */ jsx("li", { children: /* @__PURE__ */ jsxs("a", { href: assetViewerHref({ base, routePrefix, path: asset.path, locale }), title: asset.name, class: "flex min-w-0 items-center gap-hsp-xs rounded px-hsp-sm py-vsp-3xs text-small text-fg hover:bg-accent/10 hover:text-accent hover:underline focus-visible:bg-accent/10 focus-visible:text-accent focus-visible:underline", children: [
-        /* @__PURE__ */ jsx(Icon, { class: "h-icon-sm w-icon-sm shrink-0 text-muted" }),
+      return /* @__PURE__ */ jsx("li", { children: /* @__PURE__ */ jsxs("a", { href: assetViewerHref({ base, routePrefix, path: asset.path, locale }), title: asset.name, class: "group flex min-w-0 items-center gap-hsp-xs rounded px-hsp-sm py-vsp-3xs text-small text-fg hover:bg-accent/10 hover:text-accent hover:underline focus-visible:bg-accent/10 focus-visible:text-accent focus-visible:underline", children: [
+        /* @__PURE__ */ jsx(Icon, { class: "h-icon-sm w-icon-sm shrink-0 text-muted group-hover:text-accent group-focus-visible:text-accent" }),
         /* @__PURE__ */ jsx("span", { class: "min-w-0 truncate font-mono", children: basename(asset.path) }),
-        /* @__PURE__ */ jsx("span", { class: "ml-auto hidden whitespace-nowrap pl-hsp-lg text-caption text-muted sm:block", children: meta })
+        /* @__PURE__ */ jsx("span", { class: "ml-auto hidden whitespace-nowrap pl-hsp-lg text-caption text-muted sm:block group-hover:text-accent group-focus-visible:text-accent", children: meta })
       ] }) });
     })
   ] });

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;
@@ -3593,11 +3608,6 @@ site-search [data-search-results] > :is([data-search-placeholder], p) {
     color: var(--zw-color-bg);
   }
 }
-@media (hover: hover) {
-  :where(.group:hover) .group-hover\:text-fg {
-    color: var(--zw-color-fg);
-  }
-}
 @media (hover: hover) {
   :where(.group:hover) .group-hover\:bg-fg {
     background-color: var(--zw-color-fg);
@@ -3609,9 +3619,6 @@ site-search [data-search-results] > :is([data-search-placeholder], p) {
 :where(.group:focus-visible) .group-focus-visible\:text-accent {
   color: var(--zw-color-accent);
 }
-:where(.group:focus-visible) .group-focus-visible\:text-fg {
-  color: var(--zw-color-fg);
-}
 @media (hover: hover) {
   :where(.peer:hover) ~ .peer-hover\:text-accent {
     color: var(--zw-color-accent);

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/diff-loader.d.ts

@@ -0,0 +1,3 @@
+export type DiffLines = typeof import("diff").diffLines;
+/** diff's `diffLines`, or `null` when the optional peer is not installed. */
+export declare const diffLines: DiffLines | null;

package/dist/diff-loader.js

@@ -0,0 +1,13 @@
+function pickDiffLines(m) {
+  let cur = m;
+  for (let i = 0; i < 3 && cur && typeof cur === "object"; i++) {
+    const fn = cur.diffLines;
+    if (typeof fn === "function") return fn;
+    cur = cur.default;
+  }
+  return null;
+}
+const diffLines = await import("diff").then(pickDiffLines, () => null);
+export {
+  diffLines
+};

package/dist/doc-history/index.js

@@ -95,12 +95,13 @@ async function getCachedDiff(olderHash, newerHash, olderContent, newerContent, i
     diffCache.set(key, hit);
     return hit;
   }
-  const { diffLines } = await import("diff").then(
-    (m) => m,
-    () => {
-      throw new Error('Compare requires the optional peer "diff": install it to use docHistory');
-    }
+  const diffLines = await import("@takazudo/zudo-doc/diff-loader").then(
+    (m) => m.diffLines,
+    () => null
   );
+  if (!diffLines) {
+    throw new Error('Compare requires the optional peer "diff": install it to use docHistory');
+  }
   if (!isCurrent()) throw new Error("Comparison cancelled");
   const changes = diffLines(olderContent, newerContent);
   diffCache.set(key, changes);

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/katex-loader.d.ts

@@ -0,0 +1,3 @@
+export type KatexLike = typeof import("katex").default;
+/** katex's API, or `null` when the optional peer is not installed. */
+export declare const katex: KatexLike | null;

package/dist/katex-loader.js

@@ -0,0 +1,12 @@
+function pickKatex(m) {
+  let cur = m;
+  for (let i = 0; i < 3 && cur && typeof cur === "object"; i++) {
+    if (typeof cur.renderToString === "function") return cur;
+    cur = cur.default;
+  }
+  return null;
+}
+const katex = await import("katex").then(pickKatex, () => null);
+export {
+  katex
+};

package/dist/math-block/index.js

@@ -1,13 +1,8 @@
 import { jsx } from "@takazudo/zfb/zudo-react/jsx-runtime";
-function pickKatex(m) {
-  let cur = m;
-  for (let i = 0; i < 3 && cur && typeof cur === "object"; i++) {
-    if (typeof cur.renderToString === "function") return cur;
-    cur = cur.default;
-  }
-  return null;
-}
-const katex = await import("katex").then(pickKatex, () => null);
+const katex = await import("@takazudo/zudo-doc/katex-loader").then(
+  (m) => m.katex,
+  () => null
+);
 const MISSING_KATEX_MESSAGE = 'MathBlock requires the optional peer "katex": install it and set math: true';
 function MathBlock({ latex, block = false }) {
   if (!katex) throw new Error(MISSING_KATEX_MESSAGE);

package/dist/md-utils/index.d.ts

@@ -34,8 +34,14 @@ export interface MdDocFrontmatter {
  * search excerpts and llms-txt descriptions stay byte-equal across the
  * cutover, with one deliberate divergence: it also strips JSX/MDX block
  * comments (the `{/*`-delimited MDX comment form), which the legacy
- * pipeline leaked into descriptions (zudo-doc#2175). Do not add other new
- * rules without also updating the byte-equality fixtures (topic-plugin-audit).
+ * pipeline leaked into descriptions (zudo-doc#2175), and a second one
+ * (zudo-doc#4647): inline code keeps its text (only the backticks are
+ * dropped, contents protected from the later rules) instead of being deleted,
+ * and remark-directive container fence lines (`:::name[label]{attrs}`,
+ * `:::name Title`, bare `:::` closers) are removed while the label/title
+ * text is kept. Do not add
+ * other new rules without also updating the byte-equality fixtures
+ * (topic-plugin-audit).
  */
 export declare function stripMarkdown(md: string): string;
 /**

package/dist/md-utils/index.js

@@ -31,11 +31,18 @@ function decodeCharacterReferences(value) {
   ).replace(/&/g, "&");
 }
 function stripMarkdown(md) {
-  const withoutCodeCommentsAndTags = md.replace(/```[\s\S]*?```/g, "").replace(/`[^`]+`/g, "").replace(/\{\/\*[\s\S]*?\*\/\}/g, "").replace(/<[^>]+>/g, "");
-  return decodeCharacterReferences(withoutCodeCommentsAndTags).replace(/^#{1,6}\s+/gm, "").replace(/\*{1,3}([^*]+)\*{1,3}/g, "$1").replace(
+  const inlineCode = [];
+  const withoutCodeCommentsAndTags = md.replace(/```[\s\S]*?```/g, "").replace(/`([^`]+)`/g, (_m, code) => {
+    inlineCode.push(code);
+    return `\uE000${inlineCode.length - 1}\uE001`;
+  }).replace(/\{\/\*[\s\S]*?\*\/\}/g, "").replace(/<[^>]+>/g, "");
+  return decodeCharacterReferences(withoutCodeCommentsAndTags).replace(
+    /^[ \t]*:{3,}(?:[A-Za-z][\w-]*(?:\[([^\]\n]*)\])?(?:\{[^}\n]*\})?(?:[ \t]+(\S[^\n]*?))?)?[ \t]*$/gm,
+    (_m, label, title) => label ?? title ?? ""
+  ).replace(/^#{1,6}\s+/gm, "").replace(/\*{1,3}([^*]+)\*{1,3}/g, "$1").replace(
     /(^|[^\p{L}\p{N}])(_{1,3})(?=\S)([^_\n]*?\S)\2(?=$|[^\p{L}\p{N}])/gmu,
     "$1$3"
-  ).replace(/!\[[^\]]*\]\([^)]+\)/g, "").replace(/\[([^\]]+)\]\([^)]+\)/g, "$1").replace(/^>\s+/gm, "").replace(/^[-*_]{3,}\s*$/gm, "").replace(/^[\s]*[-*+]\s+/gm, "").replace(/^[\s]*\d+\.\s+/gm, "").replace(/^import\s+.*$/gm, "").replace(/^export\s+.*$/gm, "").replace(/\n{3,}/g, "\n\n").trim();
+  ).replace(/!\[[^\]]*\]\([^)]+\)/g, "").replace(/\[([^\]]+)\]\([^)]+\)/g, "$1").replace(/^>\s+/gm, "").replace(/^[-*_]{3,}\s*$/gm, "").replace(/^[\s]*[-*+]\s+/gm, "").replace(/^[\s]*\d+\.\s+/gm, "").replace(/^import\s+.*$/gm, "").replace(/^export\s+.*$/gm, "").replace(/\n{3,}/g, "\n\n").replace(/\uE000(\d+)\uE001/g, (_m, i) => inlineCode[Number(i)] ?? "").trim();
 }
 function collectMdFiles(dir) {
   const results = [];

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

@@ -23,7 +23,8 @@ function CardBody({
           item,
           locale: props.locale,
           updatedLabel: props.updatedLabel,
-          dateFormats: props.dateFormats
+          dateFormats: props.dateFormats,
+          linked
         }
       ) })
     ] }),
@@ -36,24 +37,23 @@ function DateStamp({
   locale,
   updatedLabel,
   positioned,
+  linked,
   dateFormats
 }) {
-  return /* @__PURE__ */ jsxs(
-    "time",
-    {
-      datetime: date,
-      class: positioned ? "hidden sm:flex sm:col-start-2 sm:row-start-1 sm:row-span-2 w-[6.5rem] flex-col items-end self-stretch border-l border-muted pl-hsp-xl text-muted tabular-nums" : "hidden sm:flex w-[6.5rem] flex-col items-end self-stretch border-l border-muted pl-hsp-xl text-muted tabular-nums",
-      children: [
-        /* @__PURE__ */ jsx("span", { class: "block text-title leading-tight font-medium", children: formatMonthDayLabel(date, locale, dateFormats?.monthDay) }),
-        /* @__PURE__ */ jsx("span", { class: "block text-caption", children: formatYear(date, locale, dateFormats?.year) }),
-        updated && /* @__PURE__ */ jsxs("span", { class: "mt-vsp-3xs block text-micro", children: [
-          updatedLabel,
-          " ",
-          formatMonthDayLabel(updated, locale, dateFormats?.monthDay)
-        ] })
-      ]
-    }
-  );
+  const stampClass = [
+    "hidden sm:flex w-[6.5rem] flex-col items-end self-stretch border-l border-muted pl-hsp-xl text-muted tabular-nums",
+    positioned && "sm:col-start-2 sm:row-start-1 sm:row-span-2",
+    linked && "group-hover:text-accent group-focus-visible:text-accent"
+  ].filter(Boolean).join(" ");
+  return /* @__PURE__ */ jsxs("time", { datetime: date, class: stampClass, children: [
+    /* @__PURE__ */ jsx("span", { class: "block text-title leading-tight font-medium", children: formatMonthDayLabel(date, locale, dateFormats?.monthDay) }),
+    /* @__PURE__ */ jsx("span", { class: "block text-caption", children: formatYear(date, locale, dateFormats?.year) }),
+    updated && /* @__PURE__ */ jsxs("span", { class: "mt-vsp-3xs block text-micro", children: [
+      updatedLabel,
+      " ",
+      formatMonthDayLabel(updated, locale, dateFormats?.monthDay)
+    ] })
+  ] });
 }
 function CardList(props) {
   return /* @__PURE__ */ jsx("div", { class: "grid grid-cols-1 gap-vsp-md", children: props.items.map((item) => /* @__PURE__ */ jsx(
@@ -84,7 +84,8 @@ function CardList(props) {
                   locale: props.locale,
                   updatedLabel: props.updatedLabel,
                   dateFormats: props.dateFormats,
-                  positioned: true
+                  positioned: true,
+                  linked: true
                 }
               )
             ]
@@ -107,7 +108,8 @@ function CardList(props) {
               locale: props.locale,
               updatedLabel: props.updatedLabel,
               dateFormats: props.dateFormats,
-              positioned: true
+              positioned: true,
+              linked: false
             }
           )
         ] }),
@@ -135,7 +137,8 @@ function CardList(props) {
                 locale: props.locale,
                 updatedLabel: props.updatedLabel,
                 dateFormats: props.dateFormats,
-                positioned: false
+                positioned: false,
+                linked: true
               }
             )
           ]
@@ -158,7 +161,8 @@ function CardList(props) {
             locale: props.locale,
             updatedLabel: props.updatedLabel,
             dateFormats: props.dateFormats,
-            positioned: false
+            positioned: false,
+            linked: false
           }
         )
       ] })