@takazudo/zudo-doc 8.1.3 → 9.1.0

package/dist/features.css

@@ -1350,3 +1350,113 @@ site-search [data-search-results] > :is([data-search-placeholder], p) {
 .zd-theme-pack-active-ring {
   box-shadow: 0 0 0 2px var(--color-accent);
 }
+
+/* ========================================
+ * Sidebar branch focus preview (frame + branch preview)
+ *
+ * Hovering (mouse/pen) or keyboard-focusing a category's focus frame marks
+ * exactly that branch wrapper `[data-sidebar-preview]` (one per sidebar
+ * instance — see sidebar-tree-island/branch-preview.ts). Every treatment is
+ * paint-only: background, inset box-shadow and border-color. Nothing here may
+ * change box geometry, or the preview would shift rows.
+ *
+ * The wash and leading rule live on the wrapper's own background layer, so the
+ * current-page row's `bg-fg` fill paints over them and stays readable.
+ * ======================================== */
+[data-sidebar-preview] {
+  background-color: color-mix(in oklch, var(--color-accent) 3%, transparent);
+  box-shadow: inset 2px 0 0 var(--color-accent);
+}
+
+[data-sidebar-preview] > [data-sidebar-row]:not([data-sidebar-current]) {
+  background-color: color-mix(in oklch, var(--color-accent) 7%, transparent);
+}
+
+[data-sidebar-preview] > [data-sidebar-row]:not([data-sidebar-current]) [data-sidebar-focus] {
+  color: var(--color-accent);
+  background-color: color-mix(in oklch, var(--color-accent) 7%, transparent);
+}
+
+/* Only connectors inside the previewed subtree — never the row's own elbow to
+ * its parent, which belongs to the ancestor. */
+[data-sidebar-preview] > [data-sidebar-children] [data-tree-connector] {
+  border-color: var(--color-accent);
+}
+
+/* Scope arrival: a brief wash on the newly focused root row. */
+[data-sidebar-arrived] > [data-sidebar-row]:not([data-sidebar-current]) {
+  animation: zd-sidebar-arrival 700ms ease-out;
+}
+
+@keyframes zd-sidebar-arrival {
+  0%,
+  22% {
+    background-color: color-mix(in oklch, var(--color-accent) 12%, transparent);
+    box-shadow: inset 2px 0 0 var(--color-accent);
+  }
+  100% {
+    background-color: transparent;
+    box-shadow: inset 0 0 0 transparent;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  [data-sidebar-arrived] > [data-sidebar-row]:not([data-sidebar-current]) {
+    animation: none;
+  }
+}
+
+/* Touch target: a one-tap focus frame at a comfortable size. */
+@media (pointer: coarse) {
+  /* Out-specifies the frame's w-/h- utilities, which are emitted after this file. */
+  [data-sidebar-row] [data-sidebar-focus] {
+    width: 2.5rem;
+    height: 2.75rem;
+  }
+}
+
+/* Transient tooltip for the focus frame and Restore. Appended to <body> so the
+ * sidebar's scroll viewport and the drawer's transform cannot clip it. */
+[data-sidebar-tooltip] {
+  position: fixed;
+  z-index: var(--z-index-tooltip);
+  max-width: min(18rem, calc(100vw - 1rem));
+  padding: var(--spacing-vsp-2xs) var(--spacing-hsp-sm);
+  border-radius: var(--radius-DEFAULT);
+  background-color: var(--color-fg);
+  color: var(--color-bg);
+  font-size: var(--text-caption);
+  line-height: 1.4;
+  overflow-wrap: anywhere;
+  box-shadow: 0 4px 12px color-mix(in oklch, var(--color-fg) 20%, transparent);
+}
+
+[data-sidebar-tooltip][hidden] {
+  display: none;
+}
+
+[data-sidebar-tooltip] > strong {
+  display: block;
+  font-weight: 600;
+}
+
+[data-sidebar-tooltip] > span {
+  display: block;
+  font-size: var(--text-micro);
+  opacity: 0.8;
+}
+
+@media (forced-colors: active) {
+  [data-sidebar-preview] > [data-sidebar-row] {
+    outline: 2px solid Highlight;
+    outline-offset: -2px;
+  }
+
+  [data-sidebar-preview] > [data-sidebar-children] [data-tree-connector] {
+    border-color: Highlight;
+  }
+
+  [data-sidebar-tooltip] {
+    border: 1px solid CanvasText;
+  }
+}

package/dist/footer/footer.js

@@ -51,7 +51,7 @@ function Footer(props) {
                     children: [
                       "#",
                       tag,
-                      /* @__PURE__ */ jsxs("span", { class: "opacity-60", "aria-hidden": "true", children: [
+                      /* @__PURE__ */ jsxs("span", { "data-zd-tag-count": true, class: "opacity-60", "aria-hidden": "true", children: [
                         "\xA0(",
                         count,
                         ")"

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

@@ -6,7 +6,7 @@ import ColorSchemeProvider from "../theme/color-scheme-provider.js";
 import ThemePackProvider, {
   themePackVersionMap
 } from "../theme/theme-pack-provider.js";
-import { DEFAULT_THEME_PACK_SLUG } from "../theme-pack-switcher/theme-pack-sync.js";
+import { resolveConfiguredThemePack } from "../theme-packs-registry/configured-theme-pack.js";
 import { renderAutoLogoIconSvg } from "../auto-logo/icon.js";
 import { deriveComposeMetaTitle, deriveColorSchemeGenerators } from "../chrome/derive.js";
 import { assertChromeContext } from "../chrome/assert-chrome-context.js";
@@ -99,7 +99,7 @@ function createHeadWithDefaults(ctx) {
   const { generateCssCustomProperties, generateLightDarkCssProperties } = deriveColorSchemeGenerators(ctx);
   const themePackRegistry = ctx.themePackRegistry;
   const themePackEnabled = themePackRegistry !== null ? themePackVersionMap(themePackRegistry) : null;
-  const themePackConfigured = settings.themePack ?? DEFAULT_THEME_PACK_SLUG;
+  const themePackConfigured = resolveConfiguredThemePack(settings);
   const themePackBase = withBase("/");
   const faviconLinks = resolveFaviconLinks(settings.favicon, settings.siteName, withBase);
   function HeadWithDefaults({

package/dist/html-preview-wrapper/preview-base.js

@@ -103,7 +103,7 @@ function PreviewBase({
             "button",
             {
               type: "button",
-              class: computed(() => `min-h-[44px] min-w-[44px] px-hsp-sm py-hsp-2xs text-caption border rounded-full cursor-pointer transition-[background,color,border-color] duration-150 leading-snug ${i === activeViewport.value ? "bg-accent text-bg border-accent hover:bg-accent-hover hover:border-accent-hover" : "bg-transparent text-muted border-muted hover:bg-[color-mix(in_srgb,var(--color-surface)_80%,var(--color-fg)_20%)]"}`),
+              class: computed(() => `min-h-[44px] min-w-[44px] px-hsp-sm py-hsp-2xs text-caption border rounded-full cursor-pointer transition-[background,color,border-color] duration-150 leading-snug ${i === activeViewport.value ? "bg-accent text-bg border-accent hover:bg-accent-hover hover:border-accent-hover" : "bg-transparent text-muted border-muted hover:text-fg hover:bg-[color-mix(in_srgb,var(--color-surface)_80%,var(--color-fg)_20%)]"}`),
               "aria-pressed": computed(() => i === activeViewport.value),
               "on:click": () => {
                 activeViewport.value = i;
@@ -137,7 +137,7 @@ function PreviewBase({
         "button",
         {
           type: "button",
-          class: "flex min-h-[44px] min-w-[44px] items-center w-full px-hsp-md py-hsp-sm text-caption font-medium text-muted bg-surface border-none cursor-pointer gap-hsp-xs hover:bg-[color-mix(in_srgb,var(--color-surface)_80%,var(--color-fg)_20%)]",
+          class: "flex min-h-[44px] min-w-[44px] items-center w-full px-hsp-md py-hsp-sm text-caption font-medium text-muted bg-surface border-none cursor-pointer gap-hsp-xs hover:text-fg hover:bg-[color-mix(in_srgb,var(--color-surface)_80%,var(--color-fg)_20%)]",
           "on:click": () => {
             codeOpen.value = !codeOpen.value;
           },

package/dist/icons/index.d.ts

@@ -20,3 +20,5 @@ export declare function FileImage({ class: className }: IconProps): Child;
 export declare function FileVideo({ class: className }: IconProps): Child;
 export declare function FilePdf({ class: className }: IconProps): Child;
 export declare function FileArchive({ class: className }: IconProps): Child;
+export declare function FocusFrame({ class: className }: IconProps): Child;
+export declare function RestoreArrow({ class: className }: IconProps): Child;

package/dist/icons/index.js

@@ -334,6 +334,40 @@ function FileArchive({ class: className }) {
     }
   );
 }
+function FocusFrame({ class: className }) {
+  return /* @__PURE__ */ jsx(
+    "svg",
+    {
+      class: className || void 0,
+      viewBox: "0 0 24 24",
+      fill: "none",
+      stroke: "currentColor",
+      "stroke-width": "1.65",
+      "stroke-linecap": "round",
+      "stroke-linejoin": "round",
+      "aria-hidden": "true",
+      focusable: "false",
+      children: /* @__PURE__ */ jsx("path", { d: "M8 3H5a2 2 0 0 0-2 2v3m13-5h3a2 2 0 0 1 2 2v3M3 16v3a2 2 0 0 0 2 2h3m8 0h3a2 2 0 0 0 2-2v-3" })
+    }
+  );
+}
+function RestoreArrow({ class: className }) {
+  return /* @__PURE__ */ jsx(
+    "svg",
+    {
+      class: className || void 0,
+      viewBox: "0 0 24 24",
+      fill: "none",
+      stroke: "currentColor",
+      "stroke-width": "1.65",
+      "stroke-linecap": "round",
+      "stroke-linejoin": "round",
+      "aria-hidden": "true",
+      focusable: "false",
+      children: /* @__PURE__ */ jsx("path", { d: "M3 10a9 9 0 1 1 2.6 8.4M3 4v6h6" })
+    }
+  );
+}
 export {
   ArrowLeft,
   ChevronLeft,
@@ -346,9 +380,11 @@ export {
   FilePdf,
   FileText,
   FileVideo,
+  FocusFrame,
   Folder,
   FolderOpen,
   GitHub,
   History,
+  RestoreArrow,
   Search
 };

package/dist/metainfo/doc-tags.js

@@ -20,11 +20,13 @@ function DocTags(props) {
       {
         href,
         "aria-label": `${taggedWithLabel}: ${tag}`,
+        "data-zd-tag-chip": true,
         class: "group relative inline-flex no-underline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-accent",
         children: [
           /* @__PURE__ */ jsx(
             "span",
             {
+              "data-zd-tag-chip-outline": true,
               class: "absolute inset-0 bg-muted group-hover:bg-fg",
               style: "clip-path: polygon(0 0, calc(100% - 12px) 0, 100% 50%, calc(100% - 12px) 100%, 0 100%)"
             }
@@ -32,6 +34,7 @@ function DocTags(props) {
           /* @__PURE__ */ jsxs(
             "span",
             {
+              "data-zd-tag-chip-label": true,
               class: "relative inline-flex items-center text-caption text-fg bg-bg pl-hsp-sm pr-hsp-lg py-vsp-2xs group-hover:text-bg group-hover:bg-fg",
               style: "clip-path: polygon(1px 1px, calc(100% - 13px) 1px, calc(100% - 1px) 50%, calc(100% - 13px) calc(100% - 1px), 1px calc(100% - 1px))",
               children: [

package/dist/nav-indexing/tag-nav.js

@@ -10,11 +10,13 @@ function AllTagChip({
     {
       href,
       "aria-label": `${labels.taggedWith}: ${tag}`,
+      "data-zd-tag-chip": true,
       class: "group relative inline-flex no-underline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-accent",
       children: [
         /* @__PURE__ */ jsx(
           "span",
           {
+            "data-zd-tag-chip-outline": true,
             class: "absolute inset-0 bg-muted group-hover:bg-fg",
             style: "clip-path: polygon(0 0, calc(100% - 16px) 0, 100% 50%, calc(100% - 16px) 100%, 0 100%)"
           }
@@ -22,6 +24,7 @@ function AllTagChip({
         /* @__PURE__ */ jsxs(
           "span",
           {
+            "data-zd-tag-chip-label": true,
             class: "relative inline-flex items-center text-small text-fg bg-bg pl-hsp-sm pr-hsp-xl py-vsp-2xs group-hover:text-bg group-hover:bg-fg",
             style: "clip-path: polygon(1px 1px, calc(100% - 17px) 1px, calc(100% - 1px) 50%, calc(100% - 17px) calc(100% - 1px), 1px calc(100% - 1px))",
             children: [
@@ -29,7 +32,7 @@ function AllTagChip({
                 "#",
                 tag
               ] }),
-              /* @__PURE__ */ jsxs("span", { class: "text-caption opacity-60", children: [
+              /* @__PURE__ */ jsxs("span", { "data-zd-tag-count": true, class: "text-caption opacity-60", children: [
                 "\xA0(",
                 count,
                 ")"
@@ -51,11 +54,13 @@ function PageTagChip({
     {
       href,
       "aria-label": `${labels.taggedWith}: ${tag}`,
+      "data-zd-tag-chip": true,
       class: "group relative inline-flex no-underline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-accent",
       children: [
         /* @__PURE__ */ jsx(
           "span",
           {
+            "data-zd-tag-chip-outline": true,
             class: "absolute inset-0 bg-muted group-hover:bg-fg",
             style: "clip-path: polygon(0 0, calc(100% - 12px) 0, 100% 50%, calc(100% - 12px) 100%, 0 100%)"
           }
@@ -63,6 +68,7 @@ function PageTagChip({
         /* @__PURE__ */ jsxs(
           "span",
           {
+            "data-zd-tag-chip-label": true,
             class: "relative inline-flex items-center text-caption text-fg bg-bg pl-hsp-sm pr-hsp-lg py-vsp-2xs group-hover:text-bg group-hover:bg-fg",
             style: "clip-path: polygon(1px 1px, calc(100% - 13px) 1px, calc(100% - 1px) 50%, calc(100% - 13px) calc(100% - 1px), 1px calc(100% - 1px))",
             children: [

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

@@ -28,7 +28,7 @@ export declare function getNavSectionForSlug(slug: string, headerNav: NavScopeHe
 /**
  * Filter top-level NavNodes by a headerNav categoryMatch value.
  * - `"!"` means everything NOT claimed by explicit matchers
- * - `"claude"` means nodes whose slug starts with `"claude"`
+ * - `"claude"` means nodes whose slug is `"claude"` or under `"claude/"`
  * - `undefined` means all nodes
  *
  * Parameterized version of the host's `getNavSubtree()` — receives the

package/dist/nav-scope/index.js

@@ -13,26 +13,25 @@ function getCategoryOrder(headerNav) {
 function getNavSectionForSlug(slug, headerNav) {
   const topCategory = slug.split("/")[0] ?? "";
   const all = getCategoryOrder(headerNav);
-  const explicitMatches = all.filter(
-    (cm) => cm !== "!" && topCategory.startsWith(cm)
-  );
-  if (explicitMatches.length > 0) {
-    return explicitMatches.sort((a, b) => b.length - a.length)[0];
-  }
+  const explicitMatch = all.find((cm) => cm !== "!" && topCategory === cm);
+  if (explicitMatch !== void 0) return explicitMatch;
   const defaultItem = headerNav.find(
     (item) => item.categoryMatch === "!"
   );
   return defaultItem?.categoryMatch;
 }
+function matchesCategory(slug, match) {
+  return slug === match || slug.startsWith(match + "/");
+}
 function getNavSubtree(tree, categoryMatch, headerNav) {
   if (!categoryMatch) return tree;
   if (categoryMatch === "!") {
     const explicitPrefixes = getCategoryOrder(headerNav).filter((cm) => cm !== "!");
     return tree.filter(
-      (node) => !explicitPrefixes.some((prefix) => node.slug.startsWith(prefix))
+      (node) => !explicitPrefixes.some((prefix) => matchesCategory(node.slug, prefix))
     );
   }
-  return tree.filter((node) => node.slug.startsWith(categoryMatch));
+  return tree.filter((node) => matchesCategory(node.slug, categoryMatch));
 }
 export {
   getCategoryOrder,

package/dist/page-loading/page-loading-overlay.d.ts

@@ -15,7 +15,11 @@ export interface PageLoadingOverlayProps {
  */
 export declare function buildPageLoadingOverlayBootstrap(overlayId: string): string;
 /**
- * Content loading overlay shown while a dynamic navigation is pending.
+ * Full-viewport loading overlay shown while a dynamic navigation is pending.
+ *
+ * Geometry belongs to `page-loading.css` (`position: fixed; inset: 0`); the
+ * bootstrap only toggles visibility. Header and sidebar stay stationary through
+ * their own named View Transition snapshots, not by clipping the scrim.
  *
  * Mount this once per layout (typically inside `DocLayoutWithDefaults`'s
  * `bodyEnd` slot, alongside the existing body-end providers). It is

package/dist/page-loading/page-loading-overlay.js

@@ -11,7 +11,7 @@ function buildPageLoadingOverlayBootstrap(overlayId) {
   const after = JSON.stringify(AFTER_NAVIGATE_EVENT);
   return `(function(){
 var id=${id};
-function show(){var el=document.getElementById(id);if(!el)return;var content=document.querySelector(".zd-sidebar-content-wrapper");var header=document.querySelector("body > header");el.style.left=Math.max(0,content?content.getBoundingClientRect().left:0)+"px";el.style.top=Math.max(0,header?header.getBoundingClientRect().bottom:0)+"px";el.setAttribute("data-visible","");el.setAttribute("aria-hidden","false");}
+function show(){var el=document.getElementById(id);if(!el)return;el.setAttribute("data-visible","");el.setAttribute("aria-hidden","false");}
 function hide(){var el=document.getElementById(id);if(!el)return;el.removeAttribute("data-visible");el.setAttribute("aria-hidden","true");}
 function setPending(ev){document.querySelectorAll("[data-zd-nav-pending]").forEach(function(el){el.removeAttribute("data-zd-nav-pending");});var src=ev&&ev.sourceElement;if(src&&src instanceof Element)src.setAttribute("data-zd-nav-pending","");}
 function clearPending(){document.querySelectorAll("[data-zd-nav-pending]").forEach(function(el){el.removeAttribute("data-zd-nav-pending");});}

package/dist/page-loading.css

@@ -33,7 +33,8 @@
   position: fixed;
   view-transition-name: zfb-loading;
   inset: 0;
-  /* Pending-content overlay — the bootstrap excludes the layout's chrome.
+  /* Full-viewport pending scrim, header and sidebar included. Stationary
+     chrome comes from its own named snapshots, not from clipping this box.
      --z-index-modal fallback (100) ensures the overlay stacks on top even for
      bare consumers that have not defined the token. */
   z-index: var(--z-index-modal, 100);

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

@@ -1,4 +1,5 @@
 import type { ZfbPlugin } from "@takazudo/zfb/plugins";
 export declare const ZDTP_LOADER_SPECIFIER = "@takazudo/zudo-doc/zdtp-loader";
+export declare const ZDTP_DISABLED_MESSAGE_PREFIX = "@takazudo/zdtp is not bundled";
 declare const plugin: ZfbPlugin;
 export default plugin;

package/dist/plugins/zdtp-loader.js

@@ -1,5 +1,8 @@
 const ZDTP_LOADER_SPECIFIER = "@takazudo/zudo-doc/zdtp-loader";
-const DISABLED_LOADER_SOURCE = 'throw new Error("@takazudo/zdtp is not bundled: designTokenPanel is false and bundleZdtp is not set, so this build shadows @takazudo/zudo-doc/zdtp-loader. If you reached this through @takazudo/zudo-doc/design-token-panel-bootstrap to mount your own panel, set bundleZdtp: true and install @takazudo/zdtp.");\nexport {};\n';
+const ZDTP_DISABLED_MESSAGE_PREFIX = "@takazudo/zdtp is not bundled";
+const DISABLED_LOADER_SOURCE = `throw new Error("${ZDTP_DISABLED_MESSAGE_PREFIX}: designTokenPanel is false and bundleZdtp is not set, so this build shadows @takazudo/zudo-doc/zdtp-loader. If you reached this through @takazudo/zudo-doc/design-token-panel-bootstrap to mount your own panel, set bundleZdtp: true and install @takazudo/zdtp.");
+export {};
+`;
 const plugin = {
   name: "zdtp-loader",
   setup(ctx) {
@@ -8,6 +11,7 @@ const plugin = {
 };
 var zdtp_loader_default = plugin;
 export {
+  ZDTP_DISABLED_MESSAGE_PREFIX,
   ZDTP_LOADER_SPECIFIER,
   zdtp_loader_default as default
 };

package/dist/preset.d.ts

@@ -201,10 +201,16 @@ export interface PresetSettings {
      * Active theme pack slug (ADR docs/adr/theme-packs.md, Decision 2/7).
      * Threaded into the `@takazudo/zudo-doc/plugins/theme-packs` descriptor's
      * options; the plugin's `setup()` validates it against the resolved
-     * registry and throws loudly on an unknown slug. Omit to use the package
-     * default (`"default"`).
+     * registry and throws loudly on an unknown slug. Omitted is normalized by
+     * `resolveConfiguredThemePack`: `"graphite"`, or `"default"` (Classic) when
+     * custom `colorSchemes` are passed or `colorMode` is `false`.
      */
-    themePack?: string;
+    themePack?: string | null;
+    /**
+     * The resolved `colorMode` setting. Read only to decide the omitted
+     * `themePack` (`false` keeps Classic); see {@link themePack}.
+     */
+    colorMode?: unknown;
     /**
      * Enabled pack slugs, in switcher order (ADR Decision 7). `undefined` = all
      * bundled packs. Threaded into the `@takazudo/zudo-doc/plugins/theme-packs`
@@ -353,5 +359,5 @@ export interface ZudoDocPresetResult {
  * });
  * ```
  */
-export declare function zudoDocPreset({ settings, buildDocsSchema, directiveVocabulary, translations, tagVocabulary, colorSchemes, }: ZudoDocPresetArgs): ZudoDocPresetResult;
+export declare function zudoDocPreset({ settings: inputSettings, buildDocsSchema, directiveVocabulary, translations, tagVocabulary, colorSchemes, }: ZudoDocPresetArgs): ZudoDocPresetResult;
 export declare function buildMarkdownFeatures(settings: Pick<PresetSettings, "mermaid" | "transclude">, directiveVocabulary: DirectiveVocabulary): Record<string, boolean | Record<string, unknown>>;

package/dist/preset.js

@@ -10,14 +10,24 @@ import {
   warnAmbiguousDropdownCategoryMatch
 } from "./config-assertions/index.js";
 import { zudoDocWindPreset } from "./wind/index.js";
+import { defaultColorSchemes } from "./color-schemes-defaults/index.js";
+import { resolveConfiguredThemePack } from "./theme-packs-registry/configured-theme-pack.js";
 function zudoDocPreset({
-  settings,
+  settings: inputSettings,
   buildDocsSchema,
   directiveVocabulary,
   translations,
   tagVocabulary,
   colorSchemes
 }) {
+  const settings = {
+    ...inputSettings,
+    themePack: resolveConfiguredThemePack({
+      themePack: inputSettings.themePack,
+      colorMode: inputSettings.colorMode,
+      customColorSchemes: colorSchemes !== void 0 && colorSchemes !== null && colorSchemes !== defaultColorSchemes
+    })
+  };
   assertNoCommaInVersionSlugs(settings.versions);
   assertNoEmptyStringFaviconOrLogo(settings);
   assertValidHeaderBrand(settings);

package/dist/route-context-payload/index.d.ts

@@ -15,6 +15,9 @@ export type RouteContextTranslations = Record<string, Record<string, string>>;
  *   `siteDescription`, `defaultLocale`, `locales`, `headerNav`, `themePack`).
  * - `settings` is a shallow, top-level merge over that result and wins last.
  *   Nested settings objects replace wholesale; they are never deep-merged.
+ * - A `themePack` still omitted (nullish) after that merge resolves through
+ *   `resolveConfiguredThemePack`: `"graphite"`, or `"default"` (Classic)
+ *   when `colorSchemes` data is supplied or `settings.colorMode` is `false`.
  * - `translations` deep-merges into `defaultTranslations` in two levels:
  *   locales are retained and individual keys within an overridden locale are
  *   retained unless that key is supplied by the caller.
@@ -39,7 +42,7 @@ export interface CreateRouteContextPayloadInput {
     locales?: Record<string, LocaleConfig>;
     /** Top-level navigation categories; becomes `settings.headerNav`. */
     categories?: readonly HeaderNavItem[];
-    /** Active theme-pack slug; defaults to `DEFAULT_SETTINGS.themePack`. */
+    /** Active theme-pack slug; omitted resolves via `resolveConfiguredThemePack`. */
     themePack?: string;
     /** Complete browser-facing catalog v2 manifest used to build the registry. */
     catalog?: ThemePacksCatalogManifest;

package/dist/route-context-payload/index.js

@@ -2,6 +2,7 @@ import { DEFAULT_SETTINGS } from "../settings-defaults.js";
 import { defaultTranslations } from "../i18n-defaults/index.js";
 import { defaultColorSchemes } from "../color-schemes-defaults/index.js";
 import { buildThemePackRegistry } from "../theme-packs-registry/build-registry.js";
+import { resolveConfiguredThemePack } from "../theme-packs-registry/configured-theme-pack.js";
 function mergeTranslations(overrides) {
   const merged = {};
   const localeNames = /* @__PURE__ */ new Set([
@@ -27,6 +28,11 @@ function createRouteContextPayload(input) {
     ...input.themePack !== void 0 ? { themePack: input.themePack } : {},
     ...input.settings
   };
+  settings.themePack = resolveConfiguredThemePack({
+    themePack: settings.themePack,
+    colorMode: settings.colorMode,
+    customColorSchemes: input.colorSchemes !== void 0 && input.colorSchemes !== null && input.colorSchemes !== defaultColorSchemes
+  });
   const hasRegistryOverride = Object.prototype.hasOwnProperty.call(
     input,
     "themePackRegistry"

package/dist/settings-defaults.js

@@ -86,7 +86,9 @@ const DEFAULT_SETTINGS = {
   headerNav: [],
   headerRightItems: [{ type: "component", component: "theme-toggle" }],
   packageOwnedRoutes: true,
-  themePack: "default",
+  // Omitted on purpose: `resolveConfiguredThemePack` turns an omitted pack into
+  // "graphite", or into "default" (Classic) for custom/fixed color schemes.
+  themePack: void 0,
   themePackSwitcher: false,
   themePacks: void 0
 };

package/dist/settings.d.ts

@@ -621,8 +621,10 @@ export interface Settings {
      */
     designTokenPanelConfigModule?: string;
     /**
-     * Active theme-pack slug (ADR `docs/adr/theme-packs.md`). `"default"` is
-     * the stock zudo-doc look — no pack stylesheet is loaded. Must be a member
+     * Active theme-pack slug (ADR `docs/adr/theme-packs.md`). Omitted resolves
+     * to `"graphite"`, or to `"default"` when the project supplies custom
+     * `colorSchemes` or sets `colorMode: false`. `"default"` is Classic, the
+     * original zudo-doc look — no pack stylesheet is loaded. Must be a member
      * of the resolved `themePacks` list; an unknown slug fails the build
      * loudly at plugin setup (`src/plugins/routes.ts`).
      */
@@ -634,9 +636,11 @@ export interface Settings {
     themePackSwitcher?: boolean;
     /**
      * Enabled theme-pack slugs, in switcher order. `undefined` = every bundled
-     * pack, `"default"` first then the rest in canonical (alphabetical-by-slug)
-     * order. An explicit list is authoritative: may omit `"default"`, reorder
-     * freely; duplicate or unknown slugs fail the build loudly.
+     * pack, `"graphite"` first, `"default"` (Classic) second, then the rest in
+     * canonical (alphabetical-by-slug) order. An explicit list is
+     * authoritative: may omit any pack, reorder freely; duplicate or unknown
+     * slugs fail the build loudly, and so does a list that excludes the
+     * effective `themePack`.
      */
     themePacks?: string[];
 }

package/dist/sidebar-tree-island/branch-preview.d.ts

@@ -0,0 +1,19 @@
+import { type ReadonlySignal, type Ref } from "@takazudo/zfb/zudo-react";
+/** Trigger attribute: the tooltip's title text. */
+export declare const TIP_ATTR = "data-sidebar-tip";
+/** Trigger attribute: optional secondary tooltip line. */
+export declare const TIP_DETAIL_ATTR = "data-sidebar-tip-detail";
+export interface BranchPreview {
+    /** Occurrence previewed in this sidebar instance, or null. Never persisted or broadcast. */
+    active: ReadonlySignal<string | null>;
+    clear: () => void;
+}
+/**
+ * Transient branch preview + tooltip for one sidebar island instance.
+ * Call `activate()` from the island's `onActivate`; it returns the cleanup.
+ * The desktop tree and the mobile drawer are separate instances, so each
+ * visible sidebar owns at most one preview and one tooltip.
+ */
+export declare function createBranchPreview(navRef: Ref<HTMLElement>): BranchPreview & {
+    activate: () => () => void;
+};