@takazudo/zudo-doc 8.0.0 → 8.1.1

package/dist/nav-indexing/note-tray-index-parts/date-line.d.ts

@@ -3,11 +3,13 @@ import type { JSX } from "@takazudo/zfb/zudo-react/jsx-runtime";
 import type { ResolvedDateFormats } from "../../settings.js";
 import type { NoteTrayIndexItem } from "../note-tray-index.js";
 import type { TagNavLabels } from "../types.js";
-export declare function DateLine({ item, locale, updatedLabel, dateFormats, }: {
+export declare function DateLine({ item, locale, updatedLabel, dateFormats, linked, }: {
     item: NoteTrayIndexItem;
     locale: string;
     updatedLabel: string;
     dateFormats?: ResolvedDateFormats;
+    /** Inside a `group` link: follow that link's hover/focus-visible accent. */
+    linked?: boolean;
 }): JSX.Element | null;
 export declare function ItemTags({ item, labels }: {
     item: NoteTrayIndexItem;

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

@@ -5,18 +5,25 @@ function DateLine({
   item,
   locale,
   updatedLabel,
-  dateFormats
+  dateFormats,
+  linked = false
 }) {
   if (!item.date && !item.updated) return null;
-  return /* @__PURE__ */ jsxs("span", { class: "tabular-nums text-caption text-muted", children: [
-    item.date && /* @__PURE__ */ jsx("time", { datetime: item.date, children: formatDate(item.date, locale, dateFormats?.full) }),
-    item.date && item.updated && /* @__PURE__ */ jsx("span", { "aria-hidden": "true", children: " \xB7 " }),
-    item.updated && /* @__PURE__ */ jsxs("span", { children: [
-      updatedLabel,
-      " ",
-      /* @__PURE__ */ jsx("time", { datetime: item.updated, children: formatDate(item.updated, locale, dateFormats?.full) })
-    ] })
-  ] });
+  return /* @__PURE__ */ jsxs(
+    "span",
+    {
+      class: linked ? "tabular-nums text-caption text-muted group-hover:text-accent group-focus-visible:text-accent" : "tabular-nums text-caption text-muted",
+      children: [
+        item.date && /* @__PURE__ */ jsx("time", { datetime: item.date, children: formatDate(item.date, locale, dateFormats?.full) }),
+        item.date && item.updated && /* @__PURE__ */ jsx("span", { "aria-hidden": "true", children: " \xB7 " }),
+        item.updated && /* @__PURE__ */ jsxs("span", { children: [
+          updatedLabel,
+          " ",
+          /* @__PURE__ */ jsx("time", { datetime: item.updated, children: formatDate(item.updated, locale, dateFormats?.full) })
+        ] })
+      ]
+    }
+  );
 }
 function ItemTags({ item, labels }) {
   if (!labels || !item.tagLinks?.length) return null;

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-accent group-focus-visible:text-accent" : "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 }),
@@ -20,7 +20,8 @@ function IndexList(props) {
             item,
             locale: props.locale,
             updatedLabel: props.updatedLabel,
-            dateFormats: props.dateFormats
+            dateFormats: props.dateFormats,
+            linked: Boolean(item.href)
           }
         ) })
       ] })

package/dist/plugins/diff-loader.d.ts

@@ -0,0 +1,4 @@
+import type { ZfbPlugin } from "@takazudo/zfb/plugins";
+export declare const DIFF_LOADER_SPECIFIER = "@takazudo/zudo-doc/diff-loader";
+declare const plugin: ZfbPlugin;
+export default plugin;

package/dist/plugins/diff-loader.js

@@ -0,0 +1,13 @@
+const DIFF_LOADER_SPECIFIER = "@takazudo/zudo-doc/diff-loader";
+const DISABLED_LOADER_SOURCE = 'throw new Error("diff is not bundled: docHistory is off, so this build shadows @takazudo/zudo-doc/diff-loader. To use the doc history Compare view, set docHistory: true and install diff.");\nexport {};\n';
+const plugin = {
+  name: "diff-loader",
+  setup(ctx) {
+    ctx.addVirtualModule(DIFF_LOADER_SPECIFIER, () => DISABLED_LOADER_SOURCE);
+  }
+};
+var diff_loader_default = plugin;
+export {
+  DIFF_LOADER_SPECIFIER,
+  diff_loader_default as default
+};

package/dist/plugins/katex-loader.d.ts

@@ -0,0 +1,4 @@
+import type { ZfbPlugin } from "@takazudo/zfb/plugins";
+export declare const KATEX_LOADER_SPECIFIER = "@takazudo/zudo-doc/katex-loader";
+declare const plugin: ZfbPlugin;
+export default plugin;

package/dist/plugins/katex-loader.js

@@ -0,0 +1,13 @@
+const KATEX_LOADER_SPECIFIER = "@takazudo/zudo-doc/katex-loader";
+const DISABLED_LOADER_SOURCE = 'throw new Error("katex is not bundled: math is off, so this build shadows @takazudo/zudo-doc/katex-loader. To render <MathBlock>, set math: true and install katex.");\nexport {};\n';
+const plugin = {
+  name: "katex-loader",
+  setup(ctx) {
+    ctx.addVirtualModule(KATEX_LOADER_SPECIFIER, () => DISABLED_LOADER_SOURCE);
+  }
+};
+var katex_loader_default = plugin;
+export {
+  KATEX_LOADER_SPECIFIER,
+  katex_loader_default as default
+};

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,13 +109,16 @@ 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;
     trailingSlash: boolean;
     minifyHtml?: boolean;
     mermaid: boolean;
-    /** KaTeX math rendering; when off, the optional `katex` peer is shadowed. */
+    /** KaTeX math rendering; when off, `@takazudo/zudo-doc/katex-loader` is shadowed (bare `katex` is not). */
     math?: boolean;
     /** Enable transclusion of other Markdown/MDX files. */
     transclude?: boolean;
@@ -128,6 +131,7 @@ export interface PresetSettings {
     changelogs?: PresetChangelogConfig[] | false;
     /** Metadata fields shown in the doc metadata area. */
     docMetainfoFields?: Array<"created" | "updated" | "author">;
+    /** Per-page git history; when off, `@takazudo/zudo-doc/diff-loader` is shadowed (bare `diff` is not). */
     docHistory?: boolean;
     /** Whether the doc history dropdown UI and related artifacts are enabled. */
     docHistoryUi?: boolean;

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);
@@ -337,7 +339,18 @@ 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: {} }]
+    ...resolvesBundleZdtp(settings) ? [] : [{ name: "@takazudo/zudo-doc/plugins/zdtp-loader", options: {} }],
+    // math off → shadow math-block's `@takazudo/zudo-doc/katex-loader` with a
+    // throwing virtual module so a site without the optional katex peer gets no
+    // Rolldown UNRESOLVED_IMPORT warning (#4651). The bare `katex` is untouched.
+    ...settings.math ? [] : [{ name: "@takazudo/zudo-doc/plugins/katex-loader", options: {} }],
+    // docHistory off → shadow doc-history's `@takazudo/zudo-doc/diff-loader`
+    // the same way (#4652). Gated on `docHistory`, NOT `docHistoryUi`: the
+    // dates-only mode (`docHistory: true, docHistoryUi: false`) keeps the doc
+    // history feature on, so the shadow stays out of every configuration where
+    // the Compare view is still part of the enabled feature. Bare `diff` is
+    // untouched.
+    ...settings.docHistory ? [] : [{ name: "@takazudo/zudo-doc/plugins/diff-loader", options: {} }]
   ];
 }
 export {

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/sidebar-tree-island/index.js

@@ -508,9 +508,7 @@ function TrayItem({
           rankDigits !== void 0 ? /* @__PURE__ */ jsx(
             "span",
             {
-              class: computed(
-                () => `shrink-0 tabular-nums${active.value ? "" : " text-muted"}`
-              ),
+              class: "shrink-0 tabular-nums",
               children: computed(
                 () => item.value.rank === void 0 ? "" : String(item.value.rank).padStart(rankDigits, "0")
               )
@@ -526,9 +524,7 @@ function TrayItem({
           /* @__PURE__ */ jsx(Show, { when: computed(() => showDate && !!shortDate.value), children: () => /* @__PURE__ */ jsx(
             "span",
             {
-              class: computed(
-                () => `shrink-0 tabular-nums${active.value ? "" : " text-muted"}`
-              ),
+              class: "shrink-0 tabular-nums",
               children: shortDate
             }
           ) })

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))"
         }
       ) }),
@@ -325,7 +328,7 @@ function NoteTrayRow({
     {
       href: computed(() => href.value ?? ""),
       "data-note-tray-row": true,
-      class: "flex items-start gap-hsp-sm py-vsp-2xs text-small text-fg hover:text-accent hover:underline focus:underline focus-visible:text-accent",
+      class: "group flex items-start gap-hsp-sm py-vsp-2xs text-small text-fg hover:text-accent hover:underline focus:underline focus-visible:text-accent",
       children: [
         /* @__PURE__ */ jsx(
           Show,
@@ -334,7 +337,7 @@ function NoteTrayRow({
             fallback: () => /* @__PURE__ */ jsx(
               "span",
               {
-                class: "shrink-0 font-mono tabular-nums text-caption text-muted",
+                class: "shrink-0 font-mono tabular-nums text-caption text-muted group-hover:text-accent group-focus-visible:text-accent",
                 style: computed(() => ({ width: `${width.value}ch` })),
                 children: rankLabel
               }
@@ -343,7 +346,7 @@ function NoteTrayRow({
               "time",
               {
                 datetime: computed(() => item.value.date ?? ""),
-                class: "shrink-0 font-mono tabular-nums text-caption text-muted",
+                class: "shrink-0 font-mono tabular-nums text-caption text-muted group-hover:text-accent group-focus-visible:text-accent",
                 children: computed(() => dateLabel.value ?? "")
               }
             )
@@ -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/theme-packs/brutalist/pack.css

@@ -387,8 +387,8 @@ html[data-theme-pack="brutalist"] .zd-content blockquote a {
   font-weight: 500;
 }
 /* Card-style prose links (e.g. the note-tray IndexList rank/label/
-   description spans) put their own color on group-hover: utility
-   classes (group-hover:text-fg / group-hover:text-accent), which beats
+   description/date spans) put their own color on group-hover: utility
+   classes (group-hover:text-accent), which beats
    the anchor's inherited `color` — so the anchor-level color below
    never reached that text. Measured 2.63:1 (rgb(245 245 245) on
    rgb(255 106 31), dark) / 4.06:1 (rgb(0 0 0) on rgb(194 65 12), light)

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/dist/wind.json

@@ -136,14 +136,12 @@
     "grid-rows-subgrid",
     "group",
     "group-focus-visible:text-accent",
-    "group-focus-visible:text-fg",
     "group-focus-visible:underline",
     "group-focus-within:block",
     "group-hover:bg-fg",
     "group-hover:block",
     "group-hover:text-accent",
     "group-hover:text-bg",
-    "group-hover:text-fg",
     "group-hover:underline",
     "group-open:rotate-90",
     "h-[0.5rem]",

package/eject/doc-history/index.tsx

@@ -180,16 +180,20 @@ async function getCachedDiff(
     return hit;
   }
   // Lazy-load diff — only needed after History → Compare. This keeps the
-  // module out of the eager islands bundle. `diff` is an optional peer: the
-  // literal `import("diff").then(onFulfilled, onRejected)` shape is what lets
-  // esbuild leave it unresolved when absent instead of failing the build
-  // (#4209). The rejection surfaces through DiffViewer's `.catch()` → diffError.
-  const { diffLines } = await import("diff").then(
-    (m) => m,
-    () => {
-      throw new Error('Compare requires the optional peer "diff": install it to use docHistory');
-    },
+  // module out of the eager islands bundle. `diff` is an optional peer reached
+  // ONLY through the package-owned `@takazudo/zudo-doc/diff-loader` (#4652):
+  // with `docHistory` off the preset's `diff-loader` plugin shadows that
+  // specifier with a throwing virtual module, so the bundler never tries to
+  // resolve an absent `diff` (no UNRESOLVED_IMPORT); with `docHistory: true`
+  // and diff missing the loader resolves `diffLines` to `null` (#4209). The
+  // thrown error surfaces through DiffViewer's `.catch()` → diffError.
+  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');
+  }
   // The module import cannot be aborted; a replaced comparison must not do
   // work or populate the cache after its owning scope has been disposed.
   if (!isCurrent()) throw new Error("Comparison cancelled");

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/sidebar-tree-island/index.tsx

@@ -587,10 +587,7 @@ function TrayItem({
             >
               {rankDigits !== undefined ? (
                 <span
-                  class={computed(
-                    () =>
-                      `shrink-0 tabular-nums${active.value ? "" : " text-muted"}`,
-                  )}
+                  class="shrink-0 tabular-nums"
                 >
                   {computed(() =>
                     item.value.rank === undefined
@@ -606,10 +603,7 @@ function TrayItem({
               <Show when={computed(() => showDate && !!shortDate.value)}>
                 {() => (
                   <span
-                    class={computed(
-                      () =>
-                        `shrink-0 tabular-nums${active.value ? "" : " text-muted"}`,
-                    )}
+                    class="shrink-0 tabular-nums"
                   >
                     {shortDate}
                   </span>