@takazudo/zudo-doc 1.1.0 → 1.3.0

package/dist/content.css

@@ -271,19 +271,22 @@
  * rules must live here explicitly. Closes zudolab/zudo-doc#1357 / #1444 / #1456.
  *
  * Spacing: the box carries NO margin — the separating gap to the next block is
- * supplied by that block's flow-space `margin-top` (the owl rule above). The
- * snug bottom padding keeps the body tight inside the box without inflating
- * that gap. (A missing bottom margin on the box is intentional in the flow
- * model — do NOT add one; see zudolab/zudo-doc#2188 for why the per-element
- * margin model that needed it was retired.)
+ * supplied by that block's flow-space `margin-top` (the page owl above). Blocks
+ * INSIDE `.admonition-body` get their own shorter flow gap (vsp-sm) via the
+ * nested owl below, since the page owl only reaches direct children of
+ * `.zd-content`; the box's vsp-sm bottom padding then gives the last block room
+ * so it isn't cramped against the edge. (A missing bottom margin on the box is
+ * intentional in the flow model — do NOT add one; see zudolab/zudo-doc#2188 for
+ * why the per-element margin model that needed it was retired.)
  * ======================================== */
 
 [data-admonition] {
   border-left: 4px solid var(--color-muted);
-  /* Asymmetric padding mirrors the Astro reference (`pt-vsp-md pb-vsp-2xs`) —
-   * generous space at the top, snug at the bottom — so the title row sits
-   * under generous breathing room without inflating the bottom gap. */
-  padding: var(--spacing-vsp-md) var(--spacing-hsp-lg) var(--spacing-vsp-2xs);
+  /* Generous top padding gives the title row breathing room; the bottom uses
+   * the same vsp-sm as the body inner flow (below) so the last block isn't
+   * cramped against the box edge. (Was pb-vsp-2xs — too tight once the body
+   * has multiple flowed blocks; zudolab/zudo-doc#2417.) */
+  padding: var(--spacing-vsp-md) var(--spacing-hsp-lg) var(--spacing-vsp-sm);
   background-color: color-mix(in srgb, var(--color-muted) 12%, var(--color-bg));
   border-radius: 0 var(--radius-DEFAULT) var(--radius-DEFAULT) 0;
 }
@@ -301,6 +304,19 @@
   margin-right: var(--spacing-hsp-2xs);
 }
 
+/* Flow spacing between blocks INSIDE an admonition body. The page-level
+ * `.zd-content > * + *` owl only reaches direct children of `.zd-content`, so
+ * nested blocks here had no inter-element gap (zudolab/zudo-doc#2417). The
+ * admonition is a narrower scope than the page flow, so a shorter gap
+ * (vsp-sm < the page's vsp-md) reads as natural. Layered in `zd-flow` for the
+ * same reason as the page owl: it must beat preflight's `* { margin: 0 }` but
+ * lose to an unlayered `mt-*` utility on a nested block. */
+@layer zd-flow {
+  .admonition-body > :where(* + *) {
+    margin-top: var(--spacing-vsp-sm);
+  }
+}
+
 .admonition-body > :first-child {
   margin-top: 0;
 }

package/dist/doc-body-end-islands/index.d.ts

@@ -0,0 +1,32 @@
+/** @jsxRuntime automatic */
+/** @jsxImportSource preact */
+import type { JSX } from "preact";
+/** The `settings` subset this factory reads — the three package-island flags.
+ *  A structural subset so the host can pass its full `Settings` object. */
+export interface BodyEndIslandsSettings {
+    aiAssistant: boolean;
+    imageEnlarge: boolean;
+    mermaid: boolean;
+}
+/** Dependencies injected by `_chrome.tsx` (carries the virtual-module settings). */
+export interface BodyEndIslandsDeps {
+    settings: BodyEndIslandsSettings;
+}
+/** Props for the produced `BodyEndIslands` component. */
+export interface BodyEndIslandsProps {
+    /** Base path the AI chat modal uses to construct API URLs. */
+    basePath: string;
+    /**
+     * Sr-only label rendered as the AiChatModal SSR fallback. Defaults to the
+     * English string; pass a locale-translated string for non-default locales so
+     * screen readers announce the chat entrypoint correctly before hydration.
+     */
+    aiChatBodyLabel?: string;
+}
+/**
+ * Build the package-default `BodyEndIslands` component bound to the host's
+ * serializable `settings` flags. The produced component matches the
+ * `createDocBodyEnd` `BodyEndIslands` slot contract
+ * (`(props: { basePath: string }) => JSX.Element`).
+ */
+export declare function createBodyEndIslands(deps: BodyEndIslandsDeps): (props: BodyEndIslandsProps) => JSX.Element;

package/dist/doc-body-end-islands/index.js

@@ -0,0 +1,40 @@
+import { Fragment, jsx, jsxs } from "preact/jsx-runtime";
+import { Island } from "@takazudo/zfb";
+import { AiChatModal } from "../ai-chat-modal/index.js";
+import { ImageEnlarge, ImageEnlargeSsrFallback } from "../image-enlarge/index.js";
+import { MermaidEnlarge, MermaidEnlargeSsrFallback } from "../mermaid-enlarge/index.js";
+const DEFAULT_AI_CHAT_BODY_LABEL = "Ask a question about the documentation.";
+function createBodyEndIslands(deps) {
+  const { settings } = deps;
+  function BodyEndIslands({
+    basePath,
+    aiChatBodyLabel = DEFAULT_AI_CHAT_BODY_LABEL
+  }) {
+    const aiAssistant = settings.aiAssistant ? /* @__PURE__ */ jsxs(Fragment, { children: [
+      /* @__PURE__ */ jsx("h2", { class: "sr-only", children: "AI Assistant" }),
+      Island({
+        ssrFallback: /* @__PURE__ */ jsx("p", { class: "sr-only", children: aiChatBodyLabel }),
+        children: /* @__PURE__ */ jsx(AiChatModal, { basePath })
+      })
+    ] }) : null;
+    const imageEnlarge = settings.imageEnlarge ? Island({
+      when: "idle",
+      ssrFallback: /* @__PURE__ */ jsx(ImageEnlargeSsrFallback, {}),
+      children: /* @__PURE__ */ jsx(ImageEnlarge, {})
+    }) : null;
+    const mermaidEnlarge = settings.mermaid ? Island({
+      when: "idle",
+      ssrFallback: /* @__PURE__ */ jsx(MermaidEnlargeSsrFallback, {}),
+      children: /* @__PURE__ */ jsx(MermaidEnlarge, {})
+    }) : null;
+    return /* @__PURE__ */ jsxs(Fragment, { children: [
+      aiAssistant,
+      imageEnlarge,
+      mermaidEnlarge
+    ] });
+  }
+  return BodyEndIslands;
+}
+export {
+  createBodyEndIslands
+};

package/dist/doc-page-renderer/index.js

@@ -34,7 +34,10 @@ function createRenderDocPage(deps) {
     const currentPath = version ? versionedDocsUrl(slug, version.slug, locale) : docsUrl(slug, locale);
     const canonical = absoluteUrl(currentPath);
     const navSection = getNavSectionForSlug(slug);
-    const hideSidebar = props.kind === "entry" ? props.entry.data.hide_sidebar : void 0;
+    const entryData = props.kind === "entry" ? props.entry.data : void 0;
+    const standalone = entryData?.standalone;
+    const hideSidebar = entryData ? entryData.hide_sidebar || standalone : void 0;
+    const hideToc = entryData ? entryData.hide_toc || standalone : void 0;
     const sidebarPersistKey = hideSidebar ? void 0 : `sidebar-${locale}-${navSection ?? "default"}`;
     const ContentComponent = props.kind === "entry" ? props.entry.Content : null;
     return /* @__PURE__ */ jsx(
@@ -53,7 +56,7 @@ function createRenderDocPage(deps) {
         navSection,
         sidebarPersistKey,
         hideSidebar,
-        hideToc: props.kind === "entry" ? props.entry.data.hide_toc : void 0,
+        hideToc,
         currentPath,
         currentVersion: version?.slug,
         versionSwitcher: buildInlineVersionSwitcher(slug, locale, version?.slug),

package/dist/integrations/claude-resources/generate.js

@@ -36,12 +36,11 @@ generated: true
 `;
   fs.writeFileSync(path.join(outputDir, "index.mdx"), mdx);
 }
-function writeUnlistedSubPage(outputPath, title, slug, body) {
+function writeUnlistedSubPage(outputPath, title, body) {
   fs.writeFileSync(
     outputPath,
     `---
 title: "${escapeTitle(title)}"
-slug: "${slug}"
 unlisted: true
 generated: true
 ---
@@ -55,6 +54,46 @@ function assertNotIndexReserved(nameOrSlug, errorMessage) {
     throw new Error(errorMessage);
   }
 }
+function isRepoRelativeLink(url) {
+  const trimmed = url.trim();
+  if (trimmed === "") return false;
+  if (trimmed.startsWith("#")) return false;
+  if (trimmed.startsWith("/")) return false;
+  if (/^[a-zA-Z][a-zA-Z0-9+.-]*:/.test(trimmed)) return false;
+  return true;
+}
+function downgradeRepoRelativeLinks(content) {
+  const blockPlaceholder = "\0CRLINK_BLOCK_";
+  const inlinePlaceholder = "\0CRLINK_INLINE_";
+  const codeBlocks = [];
+  const withBlocks = content.replace(/(`{3,}|~{3,})[^\n]*\n[\s\S]*?\1/g, (match) => {
+    codeBlocks.push(match);
+    return `${blockPlaceholder}${codeBlocks.length - 1}\0`;
+  });
+  const transformed = withBlocks.split(new RegExp(`(${blockPlaceholder}\\d+\0)`, "g")).map((part) => {
+    if (new RegExp(`^${blockPlaceholder}\\d+\0$`).test(part)) return part;
+    const inlineCodes = [];
+    const withInline = part.replace(
+      /(`{1,3})(?!`)([\s\S]*?[^`])\1(?!`)/g,
+      (match) => {
+        inlineCodes.push(match);
+        return `${inlinePlaceholder}${inlineCodes.length - 1}\0`;
+      }
+    );
+    const rewritten = withInline.replace(
+      /!?\[([^\]]*)\]\(([^)]+)\)/g,
+      (match, text, url) => isRepoRelativeLink(url) ? `\`${text}\`` : match
+    );
+    return rewritten.replace(
+      new RegExp(`${inlinePlaceholder}(\\d+)\0`, "g"),
+      (_, idx) => inlineCodes[Number(idx)] ?? ""
+    );
+  }).join("");
+  return transformed.replace(
+    new RegExp(`${blockPlaceholder}(\\d+)\0`, "g"),
+    (_, idx) => codeBlocks[Number(idx)] ?? ""
+  );
+}
 function findClaudeMdFiles(dir, excludeDirs) {
   const results = [];
   if (!fs.existsSync(dir)) return results;
@@ -133,7 +172,7 @@ generated: true
 
 **Path:** \`${item.relPath}\`
 
-${escapeForMdx(content.trim())}
+${escapeForMdx(downgradeRepoRelativeLinks(content.trim()))}
 `;
     fs.writeFileSync(path.join(outputDir, `${item.slug}.mdx`), mdx);
   });
@@ -297,13 +336,13 @@ generated: true
 ---
 
 ${body}`;
-    fs.writeFileSync(path.join(outputDir, `${dir}.mdx`), mdx);
-    const skillSlugBase = `claude-skills/${dir}`;
+    const skillDirOut = path.join(outputDir, dir);
+    ensureDir(skillDirOut);
+    fs.writeFileSync(path.join(skillDirOut, "index.mdx"), mdx);
     for (const ref of references) {
       writeUnlistedSubPage(
-        path.join(outputDir, `${dir}--ref-${ref.name}.mdx`),
+        path.join(skillDirOut, `ref-${ref.name}.mdx`),
         ref.title,
-        `${skillSlugBase}/ref-${ref.name}`,
         escapeForMdx(ref.content.trim())
       );
     }
@@ -316,9 +355,8 @@ ${body}`;
       const h1Match = raw.match(/^#\s+(.+)$/m);
       const title = h1Match?.[1] ?? slug;
       writeUnlistedSubPage(
-        path.join(outputDir, `${dir}--script-${slug}.mdx`),
+        path.join(skillDirOut, `script-${slug}.mdx`),
         title,
-        `${skillSlugBase}/script-${slug}`,
         escapeForMdx(raw.trim())
       );
     }
@@ -331,9 +369,8 @@ ${body}`;
       const h1Match = raw.match(/^#\s+(.+)$/m);
       const title = h1Match?.[1] ?? slug;
       writeUnlistedSubPage(
-        path.join(outputDir, `${dir}--asset-${slug}.mdx`),
+        path.join(skillDirOut, `asset-${slug}.mdx`),
         title,
-        `${skillSlugBase}/asset-${slug}`,
         escapeForMdx(raw.trim())
       );
     }

package/dist/plugins/routes.js

@@ -48,12 +48,14 @@ const plugin = definePlugin({
     const settings = options.settings ?? {};
     const translations = options.translations ?? {};
     const tagVocabulary = options.tagVocabulary ?? [];
+    const colorSchemes = options.colorSchemes ?? null;
     ctx.addVirtualModule(
       "virtual:zudo-doc-route-context",
       () => `export const routeContext = ${JSON.stringify({
         settings,
         translations,
-        tagVocabulary
+        tagVocabulary,
+        colorSchemes
       })};
 `
     );

package/dist/preset.d.ts

@@ -33,6 +33,7 @@
  *     bundles cleanly under `--platform=neutral` (verified: zero `node:*`).
  */
 import { z } from "zod";
+import type { ColorScheme } from "./color-scheme-utils.js";
 /** A single locale's content directory (`settings.locales[code]`). */
 export interface PresetLocaleConfig {
     dir: string;
@@ -72,13 +73,15 @@ export interface PresetSettings {
     claudeResources?: PresetClaudeResourcesConfig | false;
     /** "owner/repo" — when set, enables `#123` / SHA autolinks in markdown. Omit to disable entirely. */
     githubAutolinksRepo?: string;
-    /** When `true`, the preset adds the package-owned route-injection plugin
-     *  (`@takazudo/zudo-doc/plugins/routes`). On by default since the fast-follow
-     *  (#2372): the showcase and create-zudo-doc both EMIT `packageOwnedRoutes: true`
-     *  into their generated `settings.ts`. `buildPlugins` reads this value truthily
-     *  and does NO central defaulting — a hand-written settings object that OMITS the
-     *  field is treated as off; set it explicitly to control injection.
-     *  See `docs/adr/route-injection-seam.md`. */
+    /**
+     * When `true` (the **default** when omitted — #2404), the preset adds the
+     * package-owned route-injection plugin (`@takazudo/zudo-doc/plugins/routes`).
+     * Set explicitly to `false` to opt out — only needed for projects shipping
+     * their own `pages/*.tsx` stubs for every doc route. When `false` AND doc
+     * content is configured (`docsDir` non-empty and/or locales/versions set),
+     * a single `console.warn` is emitted per build as a heads-up (the build
+     * succeeds). See `docs/adr/route-injection-seam.md`. (#2404)
+     */
     packageOwnedRoutes?: boolean;
     /** Gate for the `/docs/tags` + `/docs/tags/[tag]` injected routes. */
     docTags?: boolean;
@@ -146,6 +149,19 @@ export interface ZudoDocPresetArgs {
      * `settings.packageOwnedRoutes` is true. Optional — defaults to `[]`.
      */
     tagVocabulary?: readonly PresetTagVocabularyEntry[];
+    /**
+     * The host's color-scheme palette map (`src/config/color-schemes.ts`
+     * `colorSchemes`). Only consumed when `settings.packageOwnedRoutes` is true
+     * — rides into the route-context virtual module so the package-owned routes
+     * (incl. `/404`) can emit the correct `--zd-*` CSS custom properties.
+     *
+     * Serializable JSON (ColorScheme has no function-valued fields), so it
+     * round-trips through `JSON.stringify` losslessly.
+     *
+     * Optional — when absent, package-owned routes fall back to `DEFAULT_SCHEME`
+     * (a neutral grey ramp). See `routes/_chrome.tsx`.
+     */
+    colorSchemes?: Record<string, ColorScheme>;
 }
 export interface PresetCollection {
     name: string;
@@ -199,4 +215,4 @@ export interface ZudoDocPresetResult {
  * });
  * ```
  */
-export declare function zudoDocPreset({ settings, buildDocsSchema, directiveVocabulary, translations, tagVocabulary, }: ZudoDocPresetArgs): ZudoDocPresetResult;
+export declare function zudoDocPreset({ settings, buildDocsSchema, directiveVocabulary, translations, tagVocabulary, colorSchemes, }: ZudoDocPresetArgs): ZudoDocPresetResult;

package/dist/preset.js

@@ -4,12 +4,13 @@ function zudoDocPreset({
   buildDocsSchema,
   directiveVocabulary,
   translations,
-  tagVocabulary
+  tagVocabulary,
+  colorSchemes
 }) {
   const docsSchemaJson = z.toJSONSchema(buildDocsSchema());
   return {
     collections: buildCollections(settings, docsSchemaJson),
-    plugins: buildPlugins(settings, { translations, tagVocabulary }),
+    plugins: buildPlugins(settings, { translations, tagVocabulary, colorSchemes }),
     markdown: {
       features: buildMarkdownFeatures(settings, directiveVocabulary),
       ...settings.cjkFriendly !== void 0 ? { cjkFriendly: settings.cjkFriendly } : {}
@@ -116,18 +117,41 @@ function buildPlugins(settings, routeContext) {
   const localeRecord = Object.fromEntries(
     Object.entries(settings.locales).map(([code, locale]) => [code, { dir: locale.dir }])
   );
+  const effectivePackageOwnedRoutes = settings.packageOwnedRoutes ?? true;
+  if (effectivePackageOwnedRoutes) {
+    const contentConfiguredForWarn = typeof settings.docsDir === "string" && settings.docsDir.length > 0 || Object.keys(settings.locales).length > 0 || Array.isArray(settings.versions) && settings.versions.length > 0;
+    const translationsMissing = !routeContext.translations || Object.keys(routeContext.translations).length === 0;
+    const colorSchemesMissing = !routeContext.colorSchemes;
+    if (contentConfiguredForWarn && (translationsMissing || colorSchemesMissing)) {
+      const missing = [
+        ...translationsMissing ? ["translations"] : [],
+        ...colorSchemesMissing ? ["colorSchemes"] : []
+      ].join(" and/or ");
+      console.warn(
+        `zudo-doc: packageOwnedRoutes is on but ${missing} were not passed to zudoDocPreset \u2014 package-owned routes (incl. /404) will render with fallback i18n/theme. Pass them to inherit host bindings.`
+      );
+    }
+  }
+  if (!effectivePackageOwnedRoutes) {
+    const contentConfigured = typeof settings.docsDir === "string" && settings.docsDir.length > 0 || Object.keys(settings.locales).length > 0 || Array.isArray(settings.versions) && settings.versions.length > 0;
+    if (contentConfigured) {
+      console.warn(
+        "zudo-doc: packageOwnedRoutes is off but doc content is configured \u2014 no doc routes will be injected; the build will produce only host pages/. Set packageOwnedRoutes: true in settings."
+      );
+    }
+  }
   return [
-    // Package-owned route injection — dormant by default (Decision 4). The
-    // descriptor is a BARE SPECIFIER, never an imported plugin function: the
-    // preset's node-free eval-graph guard (preset.test.ts) bundles this module
-    // under --platform=neutral, and importing the plugin would drag its
+    // Package-owned route injection — default-on (#2404). The descriptor is a
+    // BARE SPECIFIER, never an imported plugin function: the preset's node-free
+    // eval-graph guard (preset.test.ts) bundles this module under
+    // --platform=neutral, and importing the plugin would drag its
     // `injectRoute`/`node:*` graph into the config eval. The plugin's `setup`
     // hook reads `options` to (a) emit the route-context virtual module
     // (serializable settings/translations/tagVocabulary only) and (b) derive
     // the route catalog from `settings.locales` / `settings.versions`. Listed
     // FIRST so an injected route is registered before the other plugins'
     // preBuild work runs (ordering is cosmetic — injection happens in `setup`).
-    ...settings.packageOwnedRoutes ? [
+    ...effectivePackageOwnedRoutes ? [
       {
         name: "@takazudo/zudo-doc/plugins/routes",
         options: {
@@ -136,7 +160,8 @@ function buildPlugins(settings, routeContext) {
           // src/config/settings.ts), so it round-trips losslessly.
           settings,
           translations: routeContext.translations ?? {},
-          tagVocabulary: routeContext.tagVocabulary ?? []
+          tagVocabulary: routeContext.tagVocabulary ?? [],
+          colorSchemes: routeContext.colorSchemes ?? null
         }
       }
     ] : [],

package/dist/routes/404.js

@@ -5,7 +5,7 @@ import {
   HeadWithDefaults,
   HeaderWithDefaults,
   FooterWithDefaults,
-  BodyEndIslandsStub,
+  BodyEndIslands,
   composeMetaTitle
 } from "./_chrome.js";
 const frontmatter = { title: "404" };
@@ -24,7 +24,7 @@ function NotFoundPage() {
       sidebarOverride: /* @__PURE__ */ jsx(Fragment, {}),
       headerOverride: /* @__PURE__ */ jsx(HeaderWithDefaults, { lang: locale }),
       footerOverride: /* @__PURE__ */ jsx(FooterWithDefaults, { lang: locale }),
-      bodyEndComponents: /* @__PURE__ */ jsx(BodyEndIslandsStub, { basePath: settings.base ?? "/" }),
+      bodyEndComponents: /* @__PURE__ */ jsx(BodyEndIslands, { basePath: settings.base ?? "/" }),
       enableClientRouter: settings.dynamicPageTransition,
       children: /* @__PURE__ */ jsxs("div", { class: "min-h-[60vh] flex flex-col items-center justify-center px-hsp-2xl py-vsp-xl", children: [
         /* @__PURE__ */ jsx("h1", { class: "text-display font-bold mb-vsp-md", children: "404" }),

package/dist/routes/_chrome.d.ts

@@ -2,12 +2,12 @@
 /** @jsxImportSource preact */
 import type { JSX, VNode, ComponentChildren } from "preact";
 import type { DocNavNode } from "./_docs-helpers.js";
-/** Package no-op body-end islands. The host's `BodyEndIslands` wires project
- *  island bootstraps (client-router / design-token-panel) that cannot live in
- *  the package; the package default renders nothing. */
-declare function BodyEndIslandsStub(_props: {
-    basePath: string;
-}): JSX.Element;
+/** Package-default body-end islands — the package-island subset of the host's
+ *  `BodyEndIslands` (AiChatModal / ImageEnlarge / MermaidEnlarge), reconstructed
+ *  from the serializable virtual-module `settings` flags (#2406 / #2401(c)).
+ *  The host-owned bootstraps (client-router / design-token-panel) cannot live
+ *  in the package, so they are NOT included here — A2/S4 re-homes those. */
+declare const BodyEndIslands: (props: import("../doc-body-end-islands/index.js").BodyEndIslandsProps) => JSX.Element;
 export declare const composeMetaTitle: (title: string) => string;
 export declare const HeadWithDefaults: (props: import("../head-with-defaults/index.js").HeadWithDefaultsProps) => JSX.Element;
 export declare const HeaderWithDefaults: (props: import("../header-with-defaults/index.js").HeaderWithDefaultsProps) => JSX.Element;
@@ -27,6 +27,6 @@ export declare const collectTagMapForLocale: (locale: string) => Map<string, imp
     locale: string;
     children?: ComponentChildren;
 }) => JSX.Element;
-export { SiteTreeNavWrapper, BodyEndIslandsStub };
+export { SiteTreeNavWrapper, BodyEndIslands };
 export { buildDocRouteEntries, } from "./_context.js";
 export type { DocNavNode };

package/dist/routes/_chrome.js

@@ -22,7 +22,8 @@ import {
   findNode,
   firstRoutedHref,
   collectTags,
-  stableDocs
+  stableDocs,
+  colorSchemes
 } from "./_context.js";
 import { createComposeMetaTitle } from "../compose-meta-title/index.js";
 import {
@@ -35,6 +36,7 @@ import { createFooterWithDefaults } from "../footer-with-defaults/index.js";
 import { createSidebarWithDefaults } from "../sidebar-with-defaults/index.js";
 import { createSidebarPrepaint } from "../sidebar-prepaint/index.js";
 import { createDocBodyEnd } from "../doc-body-end/index.js";
+import { createBodyEndIslands } from "../doc-body-end-islands/index.js";
 import { createDocPager } from "../doc-pager/index.js";
 import { createDocPageShell } from "../doc-page-shell/index.js";
 import { createDocContentHeader } from "../doc-content-header/index.js";
@@ -92,9 +94,7 @@ const DEFAULT_SCHEME = {
 };
 const docHistoryMeta = {};
 const sidebarsConfig = {};
-function BodyEndIslandsStub(_props) {
-  return /* @__PURE__ */ jsx(Fragment, {});
-}
+const BodyEndIslands = createBodyEndIslands({ settings });
 function DocHistoryStub(_props) {
   return /* @__PURE__ */ jsx(Fragment, {});
 }
@@ -102,13 +102,28 @@ function SearchWidgetBound(props) {
   return SearchWidget({ ...props, base: withBase("/") });
 }
 const composeMetaTitle = createComposeMetaTitle(settings.siteName);
+function resolveHostScheme(key) {
+  if (!colorSchemes) return DEFAULT_SCHEME;
+  return colorSchemes[key] ?? DEFAULT_SCHEME;
+}
 const HeadWithDefaults = createHeadWithDefaults({
   settings,
   composeMetaTitle,
   withBase,
   absoluteUrl,
-  generateCssCustomProperties: () => generateCssCustomProperties(DEFAULT_SCHEME),
-  generateLightDarkCssProperties: () => generateLightDarkCssProperties(DEFAULT_SCHEME, DEFAULT_SCHEME)
+  // Called only in single-scheme mode (colorMode false): resolve via settings.colorScheme.
+  generateCssCustomProperties: () => generateCssCustomProperties(resolveHostScheme(settings.colorScheme)),
+  // Called only in light/dark mode (colorMode truthy): resolve the pair.
+  generateLightDarkCssProperties: () => {
+    const cm = settings.colorMode;
+    if (cm) {
+      return generateLightDarkCssProperties(
+        resolveHostScheme(cm.lightScheme),
+        resolveHostScheme(cm.darkScheme)
+      );
+    }
+    return generateLightDarkCssProperties(DEFAULT_SCHEME, DEFAULT_SCHEME);
+  }
 });
 function buildRootMenuItems(lang, currentVersion) {
   return buildRootMenuItemsBase(
@@ -193,7 +208,7 @@ const SidebarWithDefaults = createSidebarWithDefaults({
   t
 });
 const SidebarPrepaint = createSidebarPrepaint({ sidebarToggle: settings.sidebarToggle });
-const DocBodyEnd = createDocBodyEnd({ settings, BodyEndIslands: BodyEndIslandsStub });
+const DocBodyEnd = createDocBodyEnd({ settings, BodyEndIslands });
 const DocPager = createDocPager({ t });
 const DocMetainfoArea = createDocMetainfoArea({
   settings,
@@ -348,7 +363,7 @@ const VersionsPageView = createVersionsPageView({
     HeadWithDefaults,
     HeaderWithDefaults,
     FooterWithDefaults,
-    BodyEndIslands: BodyEndIslandsStub
+    BodyEndIslands
   }
 });
 const tagPages = createTagPages({
@@ -365,7 +380,7 @@ const tagPages = createTagPages({
     HeadWithDefaults,
     HeaderWithDefaults,
     FooterWithDefaults,
-    BodyEndIslands: BodyEndIslandsStub,
+    BodyEndIslands,
     DocHistoryArea
   }
 });
@@ -374,7 +389,7 @@ import {
   buildDocRouteEntries
 } from "./_context.js";
 export {
-  BodyEndIslandsStub,
+  BodyEndIslands,
   FooterWithDefaults,
   HeadWithDefaults,
   HeaderWithDefaults,

package/dist/routes/_context.d.ts

@@ -1,4 +1,5 @@
 import type { Settings } from "../settings.js";
+import type { ColorScheme } from "../color-scheme-utils.js";
 import type { FactoryI18n } from "../factory-context/index.js";
 import { type UrlHelpers } from "../url-helpers/index.js";
 import { toRouteSlug, toSlugParams } from "../slug/index.js";
@@ -10,10 +11,14 @@ export interface RouteContextPayload {
     settings: Settings;
     translations: Record<string, Record<string, string>>;
     tagVocabulary: readonly TagVocabularyEntry[];
+    colorSchemes: Record<string, ColorScheme> | null;
 }
 /** The serializable route-context (from the virtual module). */
 export declare const ctx: RouteContextPayload;
 export declare const settings: Settings;
+/** Host color-scheme palette map. `null` when not supplied — `_chrome.tsx`
+ *  falls back to `DEFAULT_SCHEME` in that case. */
+export declare const colorSchemes: Record<string, ColorScheme> | null;
 export declare const defaultLocale: string;
 export declare const locales: readonly string[];
 export declare function getLocaleConfig(locale: string): {

package/dist/routes/_context.js

@@ -35,6 +35,7 @@ const ctx = routeContext;
 const settings = ctx.settings;
 const translations = ctx.translations;
 const tagVocabulary = ctx.tagVocabulary;
+const colorSchemes = ctx.colorSchemes;
 const defaultLocale = settings.defaultLocale;
 const locales = [
   defaultLocale,
@@ -183,6 +184,7 @@ export {
   buildNavTree,
   collectAutoIndexNodes,
   collectTags,
+  colorSchemes,
   ctx,
   defaultLocale,
   docsUrl,

package/dist/routes/index.js

@@ -19,7 +19,7 @@ import {
   HeadWithDefaults,
   HeaderWithDefaults,
   FooterWithDefaults,
-  BodyEndIslandsStub,
+  BodyEndIslands,
   composeMetaTitle
 } from "./_chrome.js";
 const frontmatter = { title: "Home" };
@@ -53,7 +53,7 @@ function IndexPage() {
       sidebarOverride: /* @__PURE__ */ jsx(Fragment, {}),
       headerOverride: /* @__PURE__ */ jsx(HeaderWithDefaults, { lang: locale, currentPath: withBase("/") }),
       footerOverride: /* @__PURE__ */ jsx(FooterWithDefaults, { lang: locale }),
-      bodyEndComponents: /* @__PURE__ */ jsx(BodyEndIslandsStub, { basePath: settings.base ?? "/" }),
+      bodyEndComponents: /* @__PURE__ */ jsx(BodyEndIslands, { basePath: settings.base ?? "/" }),
       enableClientRouter: settings.dynamicPageTransition,
       children: [
         /* @__PURE__ */ jsx("div", { class: "flex justify-center mb-vsp-xl", children: /* @__PURE__ */ jsxs("div", { class: "flex flex-col items-center text-center gap-hsp-md lg:flex-row lg:text-left lg:gap-hsp-xl", children: [

package/dist/routes/locale-index.js

@@ -20,7 +20,7 @@ import {
   HeadWithDefaults,
   HeaderWithDefaults,
   FooterWithDefaults,
-  BodyEndIslandsStub,
+  BodyEndIslands,
   composeMetaTitle
 } from "./_chrome.js";
 const frontmatter = { title: "Home" };
@@ -63,7 +63,7 @@ function LocaleIndexPage({ params }) {
       sidebarOverride: /* @__PURE__ */ jsx(Fragment, {}),
       headerOverride: /* @__PURE__ */ jsx(HeaderWithDefaults, { lang: locale, currentPath: withBase(`/${locale}/`) }),
       footerOverride: /* @__PURE__ */ jsx(FooterWithDefaults, { lang: locale }),
-      bodyEndComponents: /* @__PURE__ */ jsx(BodyEndIslandsStub, { basePath: settings.base ?? "/" }),
+      bodyEndComponents: /* @__PURE__ */ jsx(BodyEndIslands, { basePath: settings.base ?? "/" }),
       enableClientRouter: settings.dynamicPageTransition,
       children: [
         /* @__PURE__ */ jsx("div", { class: "flex justify-center mb-vsp-xl", children: /* @__PURE__ */ jsxs("div", { class: "flex flex-col items-center text-center gap-hsp-md lg:flex-row lg:text-left lg:gap-hsp-xl", children: [

package/dist/safelist.css

@@ -1,2 +1,2 @@
 /* generated by gen-safelist.mjs — do not edit by hand */
-@source inline("-mb-px -ml-hsp-sm -translate-x-full 2xl:w-[24px] [&::-webkit-details-marker]:hidden [&_a]:text-accent [&_a]:underline [&_nav]:mb-0 [data-kbd-shortcut] [doc-history-meta] [doc-history] [doc-layout] [llms-txt] a a2 abbr about above absent absolute across activated active actual added admonition admonition- admonition-body admonition-title after after-breadcrumb after-content after-navigate after-sidebar after-title against agent agents ai-chat ai-chat-md ai-chat-trigger alert align-top all allow-same-origin allow-scripts alone already already-executed an anchor anchored and animate-spin announce antialiased any application/json application/xml applies apply-css-vars approach are area arg aria-atomic aria-busy aria-controls aria-current aria-disabled aria-expanded aria-haspopup aria-hidden aria-label aria-live aria-orientation aria-pressed aria-selected aria-valuemax aria-valuemin aria-valuenow arrive arrows article as asc aside aspect-[1200/630] aspect-square assets assigning assistant async at attach attribute attributes auto autogenerated available avoid await away b back backdrop:bg-bg/30 backdrop:bg-bg/80 backdrop:bg-overlay/60 backdrop:z-modal-backdrop background backtick backticks baked banner bare base base64 based batch be because before below best between bg bg-[#fff] bg-accent bg-bg bg-chat-assistant-bg bg-chat-user-bg bg-code-bg bg-fg bg-info/10 bg-info/5 bg-muted bg-overlay/30 bg-surface bg-transparent bg-warning/10 bg-warning/5 bi bigint bin blank blanks blob block blockquote blocks blur body body-end-components body-end-scripts boolean bootstrap border border-accent border-b border-b-2 border-b-[5px] border-bg/30 border-collapse border-danger border-dashed border-fg border-info/30 border-l border-l-0 border-l-[3px] border-muted border-none border-r border-solid border-t border-t-[2px] border-t-[3px] border-transparent border-warning/30 border-y both bottom-vsp-xl box-border br breadcrumb:end breadcrumb:start break-words browser browsers btn bug bundler but button buttons by bypassed cached call caller can cancellation cannot canonical caption carry cases cat-nav- catch category catppuccin-latte caught caution center center/contain change changed changes checkbox child ci circle cite class class-less claude claude-agents claude-commands claude-md claude-skills cleaned clear clear-css-vars clearing click client client-router client-side clip clobbering close closed closing code code-block-sr-announce code-group code-group-panel col col-resize colgroup collision color color-scheme color-scheme-changed color-scheme-provider color-tweak colorization colors command commands commit compare component component:github-link component:language-switcher component:search component:theme-toggle component:version-switcher compute computed concrete configuration configure configured connect const consumer consumes container containers containing content content-admonition content-type content-wrapper:end content-wrapper:start contents context controller controls converts copy correct correctly corrupt count covered covers cp crashes created cross-component crumb- cs css cur current cursor cursor-not-allowed cursor-pointer custom danger dark data data-active data-admonition data-base data-close-search data-group-id data-header data-header-logo data-header-nav data-header-right data-kbd-shortcut data-loading-index data-mermaid-enlarge-ready data-mermaid-rendered data-mermaid-src data-nav-item data-nav-item-dropdown data-nav-more data-nav-more-menu data-nav-more-toggle data-no-results data-open-search data-pan-active data-processed data-result-count-template data-search-count data-search-count-narrow data-search-dialog data-search-input data-search-placeholder data-search-results data-search-unavailable data-sidebar-hidden data-sidebar-resizer data-site-nav data-tab-btn data-tab-default data-tab-label data-tab-value data-tabs data-taglist-group data-testid data-theme data-theme/style data-variant data-version-banner data-version-menu data-version-switcher data-version-toggle data-zfb-transition-persist dd debounced decimal declare decoration-muted default defaults del delegated desc description design design-token-panel design-token-trigger desktop desktop-sidebar desktop-sidebar-toggle desktop-sidebar-toggle-island destructive detach detached details deterministic develop dfn diagram diagrams dialog dieser diff diff-line-added diff-line-content diff-line-empty diff-line-num diff-line-removed diff-row dir directly directories directory disabled disabled:opacity-50 disc display:none dist div dl do doc doc-card- doc-history doc-history-generate doc-history-panel doc-history-trigger doc-pager docs docs- docs-v- document document-level does double-registration drag draggable drop dropdown dropdown-child dropdown-parent dropdowns dt duration-150 duration-200 during dynamically e e2e each earlier ease-in-out edge eject ejected el element elements els else em emit emitting empty empty/undefined en enable end enlarged entire entities entries entry error escape escaped even eventually every exactly excerpt existing exists exit expected export extends failed fall fallback fallbacks falls false fast feature feed fg fields fieldset figcaption figure file fill fills finally find fire fires first fixed fixtures flag flash flat flex flex-1 flex-col flex-wrap flip flipping flips focus focus-visible:outline-2 focus-visible:outline-accent focus-visible:outline-offset-2 focus-visible:underline focus:border-accent focus:outline-none focus:underline font font-bold font-medium font-mono font-semibold footer footer- for form found free fresh from frontmatter frontmatter-preview frozen fs-extra full fully function further g gap-[0.3em] gap-[clamp(1.5rem,3vw,4rem)] gap-hsp-2xs gap-hsp-md gap-hsp-sm gap-hsp-xl gap-hsp-xs gap-vsp-2xs gap-vsp-lg gap-vsp-md gap-vsp-xs gap-x-hsp-2xs gap-x-hsp-lg gap-x-hsp-md gap-x-hsp-sm gap-x-hsp-xs gap-y-vsp-2xs gap-y-vsp-lg gap-y-vsp-md gap-y-vsp-xs gaps gate generate generation genuine geometry get github github-link go got graph gray-matter grid grid-cols-1 grid-cols-2 group group-focus-visible:text-accent 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:underline group-open:rotate-90 guard h-[0.5rem] h-[0.625rem] h-[0.875rem] h-[1.125rem] h-[1.25rem] h-[1.575rem] h-[14px] h-[1lh] h-[2rem] h-[3.5rem] h-[3rem] h-[90vh] h-[calc(100%-3rem)] h-[calc(100vh-3.5rem)] h-dvh h-full h-icon-lg h-icon-md h-icon-sm h-icon-xs h1 h2 h3 h4 h5 h6 half hand handle handled handler handlers has hash-link have head head-links head-scripts header header- header-call:end header-call:start height here hex hidden highlight highlighter history hit horizontal host hover:bg-[color-mix(in_srgb,var(--color-surface)_80%,var(--color-fg)_20%)] hover:bg-accent-hover hover:bg-accent/10 hover:bg-surface hover:border-accent hover:border-accent-hover hover:border-fg hover:text-accent hover:text-accent-hover hover:text-fg hover:underline hr href hrefs html i i2 i3 i4 icon identical idle idx if iframe image image-enlarge image/png img import important imports in inactive inbox includes index index-load info inherit initial initialised injected inline inline-block inline-flex input input-clear ins inset-0 inside install instance instanceof instead instructions intended intent into invalid inverse invoke is issues it italic item item- items items-baseline items-center items-start its itself javascript justify-between justify-center justify-end justify-start katex kbd keep keeps kept keyboard keyboard-shortcut keydown keystroke keywords khroma label landing language-switcher last:border-b-0 later launch leading-relaxed leading-snug leading-tight leaf- leak leaves leaving left left-0 left:calc legend legitimate lg lg:block lg:border lg:border-fg lg:border-solid lg:flex lg:flex-col lg:flex-row lg:gap-hsp-xl lg:grid-cols-[repeat(auto-fit,minmax(12rem,1fr))] lg:h-[90vh] lg:hidden lg:justify-start lg:m-auto lg:max-h-[90vh] lg:max-w-[52.5rem] lg:ml-[var(--zd-sidebar-w)] lg:pt-vsp-2xl lg:px-hsp-2xl lg:py-vsp-2xl lg:text-left lg:w-[90vw] lg:w-[clamp(16rem,25%,22rem)] li li2 light like likely line linger link link- links list-disc list-none listener literal literals lives llms llms-txt load local locale locales log longest-match look lostpointercapture lower lowercased luminance m m-0 m21 m6 main make malformed malicious maps mark marks matches matching math math-display math-inline max max-h-[80vh] max-h-[85vh] max-h-[90vh] max-h-full max-h-none max-w-[46rem] max-w-[80rem] max-w-[85%] max-w-[85vw] max-w-[90vw] max-w-[clamp(50rem,75vw,90rem)] max-w-full max-w-none may mb-0 mb-vsp-2xs mb-vsp-lg mb-vsp-md mb-vsp-sm mb-vsp-xl mb-vsp-xs measures measuring mechanism menu merged mermaid message messages meta metadata min-h-[60vh] min-h-[calc(100vh-3.5rem)] min-h-screen min-w-0 min-w-[10rem] min-w-[8rem] mirror mirrors missing ml-auto ml-hsp-2xl ml-hsp-lg ml-hsp-sm ml-hsp-xl mod mode mounted mouseenter mouseleave mr-hsp-sm mt-0 mt-vsp-2xl mt-vsp-2xs mt-vsp-3xs mt-vsp-lg mt-vsp-md mt-vsp-sm mt-vsp-xl must mutates mutation mutations mx-auto my-vsp-lg my-vsp-md name named native nav nav-card- navigating navigation navigations near needs new newly-swapped next no no-enlarge no-op no-repeat no-underline node node:buffer node:fs node:fs/promises node:module node:path nodes nofollow noindex non-empty non-persisted non-string none noopener noreferrer normal not not-object note now null number numeric object object-contain observe observer occurred of off og:description og:image og:image:alt og:image:height og:image:width og:title og:type og:url ol old older on once one only opacity-60 open open/close option or original other others out outline-none over overflow overflow-auto overflow-hidden overflow-x-auto overflow-y-auto overflow-y:auto overwrite own p p-0 p-hsp-lg p-hsp-md p-hsp-sm p-hsp-xl package packages padding page page-loading page-loading-overlay page-loading-spinner page-navigate-end pages paint pan panel panels parent parse parsed pass path paths pattern pb-[50vh] pb-vsp-md pb-vsp-xl pb-vsp-xs per per-call per-link permanently persisted pi pick picked picks picocolors pins pipelines pl-[1.25rem] pl-hsp-lg pl-hsp-sm pl-hsp-xl place placeholder placeholder:text-muted plain plural plus pnpm pointer-events-none pointercancel pointerdown pointermove pointerup polite polygon polyline populates port position position:fixed pr-[4px] pr-hsp-lg pr-hsp-md pr-hsp-sm pr-hsp-xl pre pre-lowercased preact preact/compat preact/hooks preact/jsx-runtime preload pres preserved produced produces production project propagating properties property props provided proxy pt-[0.15rem] pt-[2px] pt-vsp-3xs pt-vsp-md pt-vsp-sm pt-vsp-xl pt-vsp-xs ptag- public purely px px-hsp-2xl px-hsp-2xs px-hsp-lg px-hsp-md px-hsp-sm px-hsp-xl px-hsp-xs py-0 py-[2px] py-[calc(var(--spacing-vsp-xs)+0.15rem)] py-hsp-2xs py-hsp-sm py-hsp-xs py-vsp-2xs py-vsp-3xs py-vsp-lg py-vsp-md py-vsp-sm py-vsp-xl py-vsp-xs q query question r raw re-encode/decode re-lowercase re-querying re-render re-renders re-run re-running re-selects reach reached reaches read reading reads ready real real-value recorded recovers references refetch refreshes regenerate regenerates reinit reinits relative reload remains remove removed render rendered renders reorder repaint repeated repeating replaced replaces repopulate requires reserved resize resize-x resolve resolved resolves response restore restores result result-click results results-area retry return returns revision revisions rewrite right- right-0 ro robots role root rotate-180 rotate-90 round round-trip rounded rounded-[0.75rem] rounded-bl-[0.25rem] rounded-bl-[1rem] rounded-br-[0.25rem] rounded-br-[1rem] rounded-full rounded-lg rounded-t-[1rem] route router routes-src running runs runtime s safe safer same same-locale samp scanned schema-mismatch schema-missing scheme score scored script script-eval script-evaluation script-injection scripts scroll scrollbar scrolled scrollend search search-index searched section section- see sel-bg sel-fg select select-none self self-start sentinel separator server server-rendered set sets setup shadow-[0_1px_3px_color-mix(in_srgb,var(--color-fg)_8%,transparent)] shadow-lg shared shiki ship ships short shortcut should show shown shrink-0 sidebar sidebar- sidebar-toggle-island sidebar-tree-island signal similarity single singular site-search site-tree-nav-island sitemap- sites size skill skills skipping skips slash slug sm:border sm:border-muted sm:flex-row sm:grid-cols-2 sm:h-auto sm:items-center sm:justify-between sm:max-h-[80vh] sm:max-w-[52rem] sm:mx-auto sm:my-[10vh] sm:rounded-lg small smooth snapshot snapshots so soft soft-nav solid some somehow source sources space-y-vsp-2xs spacing span spans spec specifier specifiers sr-only src stale start state status stay sticky still stop stored stray string strings strip stroke-linecap stroke-linejoin stroke-width strong style style-attribute styles stylesheet sub subagents subsequent success successful summary sup support survives svg swap swapped swaps synchronous synchronously syntactically syntect t tab tab-item tab-panel tabindex table tablist tabpanel tabs tabs-container tabs-content tabs-nav tag tag- tag-item- tags tags:audit tbody td temp temp-element template temporary temporary-element terminal terms test-results text text-accent text-bg text-body text-caption text-center text-chat-assistant-text text-chat-user-text text-code-fg text-danger text-display text-fg text-heading text-info text-left text-micro text-muted text-muted/50 text-right text-small text-title text-warning text/plain textarea tfoot th that the thead their them theme theme-color theme-toggle theme/token then there these they this through throw time tip title to toggle toggle-ai-chat toggle-design-token-panel toggles token tokens tolerates too toolbar top-0 top-[3.5rem] top-full top-level total touches tp tr tracked tracking-wider trade-off transition transition-[background,color,border-color] transition-[left,color] transition-colors transition-transform translate-x-0 transparent treats tree tree-child- tree-item- tree-top- trick trigger trigger:ai-chat trigger:design-token-panel triggers true truncate truncated try turn twitter:card twitter:creator twitter:description twitter:image twitter:site twitter:title two type u ul unavailable unchanged undefined under underline understand unknown unmaintained unobserve unreadable unrelated unreleased unreliable unset unsupported up uppercase usage use used user uses utf-8 utf8 utilities v v2 val value value-reader values var variable version version- version-menu version-switcher vertical via video viewport virtual:zudo-doc-route-context visible vitesse-dark vocabulary w w-1/2 w-[0.5rem] w-[0.625rem] w-[0.875rem] w-[1.125rem] w-[1.575rem] w-[1.5rem] w-[1.75rem] w-[14px] w-[16px] w-[16rem] w-[18px] w-[280px] w-[2rem] w-[320px] w-[90vw] w-[var(--zd-sidebar-w)] w-dvw w-full w-icon-lg w-icon-md w-icon-sm w-icon-xs want warning was watching wbr wbr- we website went what when where whereas whether which while whitespace-nowrap whitespace-pre whole will with without word working worktrees would wrap wrapper wrappers written wrong wrote xl:flex xl:hidden y-scrollbar yet you your z-dropdown z-local-1 z-modal z-modal-backdrop z-sidebar z-toolbar zd-content zd-desktop-sidebar-toggle zd-doc-content-band zd-enlarge-btn zd-enlarge-dialog zd-enlarge-dialog-close zd-enlargeable zd-html-preview-code zd-mermaid-dialog zd-mermaid-enlargeable zd-mermaid-tool-btn zd-mermaid-toolbar zd-mermaid-transform zd-mermaid-viewport zd-sidebar-content-wrapper zd-sidebar-open zfb zfb:after-swap zfb:before-preparation zod zoom zudo-doc-design-tokens/v1 zudo-doc-sidebar-visible zudo-doc-sidebar-width zudo-doc-theme zudo-doc-theme-bridge");
+@source inline("-mb-px -ml-hsp-sm -translate-x-full 2xl:w-[24px] [&::-webkit-details-marker]:hidden [&_a]:text-accent [&_a]:underline [&_nav]:mb-0 [data-kbd-shortcut] [doc-history-meta] [doc-history] [doc-layout] [llms-txt] a a2 abbr about above absent absolute across activated active actual added admonition admonition- admonition-body admonition-title after after-breadcrumb after-content after-navigate after-sidebar after-title against agent agents ai-chat ai-chat-md ai-chat-trigger alert align-top all allow-same-origin allow-scripts alone already already-executed an anchor anchored and and/or animate-spin announce antialiased any application/json application/xml applies apply-css-vars approach are area arg aria-atomic aria-busy aria-controls aria-current aria-disabled aria-expanded aria-haspopup aria-hidden aria-label aria-live aria-orientation aria-pressed aria-selected aria-valuemax aria-valuemin aria-valuenow arrive arrows article as asc aside aspect-[1200/630] aspect-square asset- assets assigning assistant async at attach attribute attributes auto autogenerated available avoid await away b back backdrop:bg-bg/30 backdrop:bg-bg/80 backdrop:bg-overlay/60 backdrop:z-modal-backdrop background backtick backticks baked banner bare base base64 based batch be because before below best between bg bg-[#fff] bg-accent bg-bg bg-chat-assistant-bg bg-chat-user-bg bg-code-bg bg-fg bg-info/10 bg-info/5 bg-muted bg-overlay/30 bg-surface bg-transparent bg-warning/10 bg-warning/5 bi bigint bin blank blanks blob block blockquote blocks blur body body-end-components body-end-scripts boolean bootstrap border border-accent border-b border-b-2 border-b-[5px] border-bg/30 border-collapse border-danger border-dashed border-fg border-info/30 border-l border-l-0 border-l-[3px] border-muted border-none border-r border-solid border-t border-t-[2px] border-t-[3px] border-transparent border-warning/30 border-y both bottom-vsp-xl box-border br breadcrumb:end breadcrumb:start break-words browser browsers btn bug build bundler but button buttons by bypassed cached call caller can cancellation cannot canonical caption carry cases cat-nav- catch category catppuccin-latte caught caution center center/contain change changed changes checkbox child ci circle cite class class-less claude claude-agents claude-commands claude-md claude-skills cleaned clear clear-css-vars clearing click client client-router client-side clip clobbering close closed closing code code-block-sr-announce code-group code-group-panel col col-resize colgroup collision color color-scheme color-scheme-changed color-scheme-provider color-tweak colorization colors command commands commit compare component component:github-link component:language-switcher component:search component:theme-toggle component:version-switcher compute computed concrete configuration configure configured connect const consumer consumes container containers containing content content-admonition content-type content-wrapper:end content-wrapper:start contents context controller controls converts copy correct correctly corrupt count covered covers cp crashes created cross-component crumb- cs css cur current cursor cursor-not-allowed cursor-pointer custom danger dark data data-active data-admonition data-base data-close-search data-group-id data-header data-header-logo data-header-nav data-header-right data-kbd-shortcut data-loading-index data-mermaid-enlarge-ready data-mermaid-rendered data-mermaid-src data-nav-item data-nav-item-dropdown data-nav-more data-nav-more-menu data-nav-more-toggle data-no-results data-open-search data-pan-active data-processed data-result-count-template data-search-count data-search-count-narrow data-search-dialog data-search-input data-search-placeholder data-search-results data-search-unavailable data-sidebar-hidden data-sidebar-resizer data-site-nav data-tab-btn data-tab-default data-tab-label data-tab-value data-tabs data-taglist-group data-testid data-theme data-theme/style data-variant data-version-banner data-version-menu data-version-switcher data-version-toggle data-zfb-transition-persist dd debounced decimal declare decoration-muted default defaults del delegated desc description design design-token-panel design-token-trigger desktop desktop-sidebar desktop-sidebar-toggle desktop-sidebar-toggle-island destructive detach detached details deterministic develop dfn diagram diagrams dialog dieser diff diff-line-added diff-line-content diff-line-empty diff-line-num diff-line-removed diff-row dir directly directories directory disabled disabled:opacity-50 disc display:none dist div dl do doc doc-card- doc-history doc-history-generate doc-history-panel doc-history-trigger doc-pager docs docs- docs-v- document document-level does double-registration drag draggable drop dropdown dropdown-child dropdown-parent dropdowns dt duration-150 duration-200 during dynamically e e2e each earlier ease-in-out edge eject ejected el element elements els else em emit emitting empty empty/undefined en enable end enlarged entire entities entries entry error escape escaped even eventually every exactly excerpt existing exists exit expected export extends failed fall fallback fallbacks falls false fast feature feed fg fields fieldset figcaption figure file fill fills finally find fire fires first fixed fixtures flag flash flat flex flex-1 flex-col flex-wrap flip flipping flips focus focus-visible:outline-2 focus-visible:outline-accent focus-visible:outline-offset-2 focus-visible:underline focus:border-accent focus:outline-none focus:underline font font-bold font-medium font-mono font-semibold footer footer- for form found free fresh from frontmatter frontmatter-preview frozen fs-extra full fully function further g gap-[0.3em] gap-[clamp(1.5rem,3vw,4rem)] gap-hsp-2xs gap-hsp-md gap-hsp-sm gap-hsp-xl gap-hsp-xs gap-vsp-2xs gap-vsp-lg gap-vsp-md gap-vsp-xs gap-x-hsp-2xs gap-x-hsp-lg gap-x-hsp-md gap-x-hsp-sm gap-x-hsp-xs gap-y-vsp-2xs gap-y-vsp-lg gap-y-vsp-md gap-y-vsp-xs gaps gate generate generation genuine geometry get github github-link go got graph gray-matter grid grid-cols-1 grid-cols-2 group group-focus-visible:text-accent 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:underline group-open:rotate-90 guard h-[0.5rem] h-[0.625rem] h-[0.875rem] h-[1.125rem] h-[1.25rem] h-[1.575rem] h-[14px] h-[1lh] h-[2rem] h-[3.5rem] h-[3rem] h-[90vh] h-[calc(100%-3rem)] h-[calc(100vh-3.5rem)] h-dvh h-full h-icon-lg h-icon-md h-icon-sm h-icon-xs h1 h2 h3 h4 h5 h6 half hand handle handled handler handlers has hash-link have head head-links head-scripts header header- header-call:end header-call:start height here hex hidden highlight highlighter history hit horizontal host hover:bg-[color-mix(in_srgb,var(--color-surface)_80%,var(--color-fg)_20%)] hover:bg-accent-hover hover:bg-accent/10 hover:bg-surface hover:border-accent hover:border-accent-hover hover:border-fg hover:text-accent hover:text-accent-hover hover:text-fg hover:underline hr href hrefs html i i18n/theme. i2 i3 i4 icon identical idle idx if iframe image image-enlarge image/png img import important imports in inactive inbox includes index index-load info inherit initial initialised injected inline inline-block inline-flex input input-clear ins inset-0 inside install instance instanceof instead instructions intended intent into invalid inverse invoke is issues it italic item item- items items-baseline items-center items-start its itself javascript justify-between justify-center justify-end justify-start katex kbd keep keeps kept keyboard keyboard-shortcut keydown keystroke keywords khroma label landing language-switcher last:border-b-0 later launch leading-relaxed leading-snug leading-tight leaf- leak leaves leaving left left-0 left:calc legend legitimate lg lg:block lg:border lg:border-fg lg:border-solid lg:flex lg:flex-col lg:flex-row lg:gap-hsp-xl lg:grid-cols-[repeat(auto-fit,minmax(12rem,1fr))] lg:h-[90vh] lg:hidden lg:justify-start lg:m-auto lg:max-h-[90vh] lg:max-w-[52.5rem] lg:ml-[var(--zd-sidebar-w)] lg:pt-vsp-2xl lg:px-hsp-2xl lg:py-vsp-2xl lg:text-left lg:w-[90vw] lg:w-[clamp(16rem,25%,22rem)] li li2 light like likely line linger link link- links list-disc list-none listener literal literals lives llms llms-txt load local locale locales log longest-match look lostpointercapture lower lowercased luminance m m-0 m21 m6 main make malformed malicious maps mark marks matches matching math math-display math-inline max max-h-[80vh] max-h-[85vh] max-h-[90vh] max-h-full max-h-none max-w-[46rem] max-w-[80rem] max-w-[85%] max-w-[85vw] max-w-[90vw] max-w-[clamp(50rem,75vw,90rem)] max-w-full max-w-none may mb-0 mb-vsp-2xs mb-vsp-lg mb-vsp-md mb-vsp-sm mb-vsp-xl mb-vsp-xs measures measuring mechanism menu merged mermaid message messages meta metadata min-h-[60vh] min-h-[calc(100vh-3.5rem)] min-h-screen min-w-0 min-w-[10rem] min-w-[8rem] mirror mirrors missing ml-auto ml-hsp-2xl ml-hsp-lg ml-hsp-sm ml-hsp-xl mod mode mounted mouseenter mouseleave mr-hsp-sm mt-0 mt-vsp-2xl mt-vsp-2xs mt-vsp-3xs mt-vsp-lg mt-vsp-md mt-vsp-sm mt-vsp-xl must mutates mutation mutations mx-auto my-vsp-lg my-vsp-md name named native nav nav-card- navigating navigation navigations near needs new newly-swapped next no no-enlarge no-op no-repeat no-underline node node:buffer node:fs node:fs/promises node:module node:path nodes nofollow noindex non-empty non-persisted non-string none noopener noreferrer normal not not-object note now null number numeric object object-contain observe observer occurred of off og:description og:image og:image:alt og:image:height og:image:width og:title og:type og:url ol old older on once one only opacity-60 open open/close option or original other others out outline-none over overflow overflow-auto overflow-hidden overflow-x-auto overflow-y-auto overflow-y:auto overwrite own p p-0 p-hsp-lg p-hsp-md p-hsp-sm p-hsp-xl package package-owned packages padding page page-loading page-loading-overlay page-loading-spinner page-navigate-end pages pages/. paint pan panel panels parent parse parsed pass passed path paths pattern pb-[50vh] pb-vsp-md pb-vsp-xl pb-vsp-xs per per-call per-link permanently persisted pi pick picked picks picocolors pins pipelines pl-[1.25rem] pl-hsp-lg pl-hsp-sm pl-hsp-xl place placeholder placeholder:text-muted plain plural plus pnpm pointer-events-none pointercancel pointerdown pointermove pointerup polite polygon polyline populates port position position:fixed pr-[4px] pr-hsp-lg pr-hsp-md pr-hsp-sm pr-hsp-xl pre pre-lowercased preact preact/compat preact/hooks preact/jsx-runtime preload pres preserved produce produced produces production project propagating properties property props provided proxy pt-[0.15rem] pt-[2px] pt-vsp-3xs pt-vsp-md pt-vsp-sm pt-vsp-xl pt-vsp-xs ptag- public purely px px-hsp-2xl px-hsp-2xs px-hsp-lg px-hsp-md px-hsp-sm px-hsp-xl px-hsp-xs py-0 py-[2px] py-[calc(var(--spacing-vsp-xs)+0.15rem)] py-hsp-2xs py-hsp-sm py-hsp-xs py-vsp-2xs py-vsp-3xs py-vsp-lg py-vsp-md py-vsp-sm py-vsp-xl py-vsp-xs q query question r raw re-encode/decode re-lowercase re-querying re-render re-renders re-run re-running re-selects reach reached reaches read reading reads ready real real-value recorded recovers ref- references refetch refreshes regenerate regenerates reinit reinits relative reload remains remove removed render rendered renders reorder repaint repeated repeating replaced replaces repopulate requires reserved resize resize-x resolve resolved resolves response restore restores result result-click results results-area retry return returns revision revisions rewrite right- right-0 ro robots role root rotate-180 rotate-90 round round-trip rounded rounded-[0.75rem] rounded-bl-[0.25rem] rounded-bl-[1rem] rounded-br-[0.25rem] rounded-br-[1rem] rounded-full rounded-lg rounded-t-[1rem] route router routes routes-src running runs runtime s safe safer same same-locale samp scanned schema-mismatch schema-missing scheme score scored script script- script-eval script-evaluation script-injection scripts scroll scrollbar scrolled scrollend search search-index searched section section- see sel-bg sel-fg select select-none self self-start sentinel separator server server-rendered set sets setup shadow-[0_1px_3px_color-mix(in_srgb,var(--color-fg)_8%,transparent)] shadow-lg shared shiki ship ships short shortcut should show shown shrink-0 sidebar sidebar- sidebar-toggle-island sidebar-tree-island signal similarity single singular site-search site-tree-nav-island sitemap- sites size skill skills skipping skips slash slug sm:border sm:border-muted sm:flex-row sm:grid-cols-2 sm:h-auto sm:items-center sm:justify-between sm:max-h-[80vh] sm:max-w-[52rem] sm:mx-auto sm:my-[10vh] sm:rounded-lg small smooth snapshot snapshots so soft soft-nav solid some somehow source sources space-y-vsp-2xs spacing span spans spec specifier specifiers sr-only src stale start state status stay sticky still stop stored stray string strings strip stroke-linecap stroke-linejoin stroke-width strong style style-attribute styles stylesheet sub subagents subsequent success successful summary sup support survives svg swap swapped swaps synchronous synchronously syntactically syntect t tab tab-item tab-panel tabindex table tablist tabpanel tabs tabs-container tabs-content tabs-nav tag tag- tag-item- tags tags:audit tbody td temp temp-element template temporary temporary-element terminal terms test-results text text-accent text-bg text-body text-caption text-center text-chat-assistant-text text-chat-user-text text-code-fg text-danger text-display text-fg text-heading text-info text-left text-micro text-muted text-muted/50 text-right text-small text-title text-warning text/plain textarea tfoot th that the thead their them theme theme-color theme-toggle theme/token then there these they this through throw time tip title to toggle toggle-ai-chat toggle-design-token-panel toggles token tokens tolerates too toolbar top-0 top-[3.5rem] top-full top-level total touches tp tr tracked tracking-wider trade-off transition transition-[background,color,border-color] transition-[left,color] transition-colors transition-transform translate-x-0 translations transparent treats tree tree-child- tree-item- tree-top- trick trigger trigger:ai-chat trigger:design-token-panel triggers true truncate truncated try turn twitter:card twitter:creator twitter:description twitter:image twitter:site twitter:title two type u ul unavailable unchanged undefined under underline understand unknown unmaintained unobserve unreadable unrelated unreleased unreliable unset unsupported up uppercase usage use used user uses utf-8 utf8 utilities v v2 val value value-reader values var variable version version- version-menu version-switcher vertical via video viewport virtual:zudo-doc-route-context visible vitesse-dark vocabulary w w-1/2 w-[0.5rem] w-[0.625rem] w-[0.875rem] w-[1.125rem] w-[1.575rem] w-[1.5rem] w-[1.75rem] w-[14px] w-[16px] w-[16rem] w-[18px] w-[280px] w-[2rem] w-[320px] w-[90vw] w-[var(--zd-sidebar-w)] w-dvw w-full w-icon-lg w-icon-md w-icon-sm w-icon-xs want warning was watching wbr wbr- we website went were what when where whereas whether which while whitespace-nowrap whitespace-pre whole will with without word working worktrees would wrap wrapper wrappers written wrong wrote xl:flex xl:hidden y-scrollbar yet you your z-dropdown z-local-1 z-modal z-modal-backdrop z-sidebar z-toolbar zd-content zd-desktop-sidebar-toggle zd-doc-content-band zd-enlarge-btn zd-enlarge-dialog zd-enlarge-dialog-close zd-enlargeable zd-html-preview-code zd-mermaid-dialog zd-mermaid-enlargeable zd-mermaid-tool-btn zd-mermaid-toolbar zd-mermaid-transform zd-mermaid-viewport zd-sidebar-content-wrapper zd-sidebar-open zfb zfb:after-swap zfb:before-preparation zod zoom zudo-doc-design-tokens/v1 zudo-doc-sidebar-visible zudo-doc-sidebar-width zudo-doc-theme zudo-doc-theme-bridge");

package/dist/settings.d.ts

@@ -254,17 +254,19 @@ export interface Settings {
     headerRightItems: HeaderRightItem[];
     /**
      * Build-time package-owned route injection (epic Package-First Finale #2356,
-     * ADR `docs/adr/route-injection-seam.md`). When `true`, the preset adds the
-     * `@takazudo/zudo-doc/plugins/routes` plugin, which injects the doc routes
-     * from the package instead of requiring project-shipped `pages/*.tsx` stubs.
+     * ADR `docs/adr/route-injection-seam.md`). When `true` (the **default** when
+     * omitted — #2404), the preset adds the `@takazudo/zudo-doc/plugins/routes`
+     * plugin, which injects the doc routes from the package instead of requiring
+     * project-shipped `pages/*.tsx` stubs.
      *
-     * On by default since the fast-follow (#2372 — upstream zfb dev-render support
-     * landed): the showcase and create-zudo-doc emit `packageOwnedRoutes: true` into
-     * their generated `settings.ts`. The preset reads this value truthily with no
-     * central defaulting, so a hand-written settings object that omits the field is
-     * treated as off. Any injected route whose URL shape collides with a kept
-     * `pages/` stub is silently dropped (user `pages/` wins), so existing stubs
-     * are a harmless no-op.
+     * Set explicitly to `false` only if your project ships its own `pages/*.tsx`
+     * stubs for every doc route. Any injected route whose URL shape collides with
+     * a kept `pages/` stub is silently dropped (user `pages/` wins), so existing
+     * stubs are a harmless no-op if you later re-enable this.
+     *
+     * When `false` AND doc content is configured (`docsDir` non-empty and/or
+     * locales/versions set), a single `console.warn` is emitted per build to
+     * flag a potentially-empty build (#2404). No throw — the build succeeds.
      */
     packageOwnedRoutes?: boolean;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@takazudo/zudo-doc",
-  "version": "1.1.0",
+  "version": "1.3.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",
@@ -392,6 +392,10 @@
       "types": "./dist/doc-body-end/index.d.ts",
       "default": "./dist/doc-body-end/index.js"
     },
+    "./doc-body-end-islands": {
+      "types": "./dist/doc-body-end-islands/index.d.ts",
+      "default": "./dist/doc-body-end-islands/index.js"
+    },
     "./doc-history-area": {
       "types": "./dist/doc-history-area/index.d.ts",
       "default": "./dist/doc-history-area/index.js"
@@ -511,9 +515,9 @@
   ],
   "peerDependencies": {
     "preact": "^10.29.1",
-    "@takazudo/zfb": "^0.1.0-next.67",
-    "@takazudo/zfb-runtime": "^0.1.0-next.67",
-    "@takazudo/zudo-doc-history-server": "^1.0.2",
+    "@takazudo/zfb": "^0.1.0-next.70",
+    "@takazudo/zfb-runtime": "^0.1.0-next.70",
+    "@takazudo/zudo-doc-history-server": "^1.2.0",
     "@takazudo/zdtp": "^0.3.3",
     "shiki": "^4.0.2",
     "zod": "^4.3.6",
@@ -555,8 +559,8 @@
     "typescript": "^5.0.0",
     "vitest": "^4.1.0",
     "zod": "^4.3.6",
-    "@takazudo/zfb": "0.1.0-next.67",
-    "@takazudo/zfb-runtime": "0.1.0-next.67"
+    "@takazudo/zfb": "0.1.0-next.70",
+    "@takazudo/zfb-runtime": "0.1.0-next.70"
   },
   "scripts": {
     "build": "tsup && tsc -p tsconfig.build.json",

package/routes-src/404.tsx

@@ -10,7 +10,7 @@ import {
   HeadWithDefaults,
   HeaderWithDefaults,
   FooterWithDefaults,
-  BodyEndIslandsStub,
+  BodyEndIslands,
   composeMetaTitle,
 } from "./_chrome.js";
 
@@ -31,7 +31,7 @@ export default function NotFoundPage(): JSX.Element {
       sidebarOverride={<></>}
       headerOverride={<HeaderWithDefaults lang={locale} />}
       footerOverride={<FooterWithDefaults lang={locale} />}
-      bodyEndComponents={<BodyEndIslandsStub basePath={settings.base ?? "/"} />}
+      bodyEndComponents={<BodyEndIslands basePath={settings.base ?? "/"} />}
       enableClientRouter={settings.dynamicPageTransition}
     >
       <div class="min-h-[60vh] flex flex-col items-center justify-center px-hsp-2xl py-vsp-xl">

package/routes-src/_chrome.tsx

@@ -52,6 +52,7 @@ import {
   firstRoutedHref,
   collectTags,
   stableDocs,
+  colorSchemes,
 } from "./_context.js";
 import type { CategoryMeta, DocNavNode } from "./_docs-helpers.js";
 
@@ -67,6 +68,7 @@ import { createFooterWithDefaults } from "@takazudo/zudo-doc/footer-with-default
 import { createSidebarWithDefaults } from "@takazudo/zudo-doc/sidebar-with-defaults";
 import { createSidebarPrepaint } from "@takazudo/zudo-doc/sidebar-prepaint";
 import { createDocBodyEnd } from "@takazudo/zudo-doc/doc-body-end";
+import { createBodyEndIslands } from "@takazudo/zudo-doc/doc-body-end-islands";
 import { createDocPager } from "@takazudo/zudo-doc/doc-pager";
 import { createDocPageShell } from "@takazudo/zudo-doc/doc-page-shell";
 import { createDocContentHeader } from "@takazudo/zudo-doc/doc-content-header";
@@ -128,12 +130,12 @@ const docHistoryMeta: Record<string, never> = {};
  *  tree. The project `sidebars` config is host-bound (A2). */
 const sidebarsConfig: Record<string, never> = {};
 
-/** Package no-op body-end islands. The host's `BodyEndIslands` wires project
- *  island bootstraps (client-router / design-token-panel) that cannot live in
- *  the package; the package default renders nothing. */
-function BodyEndIslandsStub(_props: { basePath: string }): JSX.Element {
-  return <></>;
-}
+/** Package-default body-end islands — the package-island subset of the host's
+ *  `BodyEndIslands` (AiChatModal / ImageEnlarge / MermaidEnlarge), reconstructed
+ *  from the serializable virtual-module `settings` flags (#2406 / #2401(c)).
+ *  The host-owned bootstraps (client-router / design-token-panel) cannot live
+ *  in the package, so they are NOT included here — A2/S4 re-homes those. */
+const BodyEndIslands = createBodyEndIslands({ settings });
 
 /** Package no-op DocHistory island stub — renders an empty fragment (the
  *  `DocHistoryComponent` contract requires a VNode, not null). */
@@ -162,14 +164,38 @@ function SearchWidgetBound(props: {
 
 export const composeMetaTitle = createComposeMetaTitle(settings.siteName);
 
+// Scheme-selection: resolve the active color scheme(s) from the host
+// `colorSchemes` map supplied via the virtual module. Falls back to
+// `DEFAULT_SCHEME` for any missing key or when `colorSchemes` is absent.
+// `generateCssCustomProperties` is called in single-scheme mode
+// (`settings.colorMode` is false); `generateLightDarkCssProperties` in
+// light/dark mode. Both delegate to DEFAULT_SCHEME when `colorSchemes` is null.
+function resolveHostScheme(key: string): ColorScheme {
+  if (!colorSchemes) return DEFAULT_SCHEME;
+  return colorSchemes[key] ?? DEFAULT_SCHEME;
+}
+
 export const HeadWithDefaults = createHeadWithDefaults({
   settings,
   composeMetaTitle,
   withBase,
   absoluteUrl,
-  generateCssCustomProperties: () => generateCssCustomProperties(DEFAULT_SCHEME),
-  generateLightDarkCssProperties: () =>
-    generateLightDarkCssProperties(DEFAULT_SCHEME, DEFAULT_SCHEME),
+  // Called only in single-scheme mode (colorMode false): resolve via settings.colorScheme.
+  generateCssCustomProperties: () =>
+    generateCssCustomProperties(resolveHostScheme(settings.colorScheme)),
+  // Called only in light/dark mode (colorMode truthy): resolve the pair.
+  generateLightDarkCssProperties: () => {
+    const cm = settings.colorMode;
+    if (cm) {
+      return generateLightDarkCssProperties(
+        resolveHostScheme(cm.lightScheme),
+        resolveHostScheme(cm.darkScheme),
+      );
+    }
+    // Should not be reached (head-with-defaults only calls this when colorMode
+    // is truthy), but guard the contract by falling back to DEFAULT_SCHEME.
+    return generateLightDarkCssProperties(DEFAULT_SCHEME, DEFAULT_SCHEME);
+  },
 });
 
 // ---------------------------------------------------------------------------
@@ -272,7 +298,7 @@ export const SidebarWithDefaults = createSidebarWithDefaults({
 });
 
 const SidebarPrepaint = createSidebarPrepaint({ sidebarToggle: settings.sidebarToggle });
-const DocBodyEnd = createDocBodyEnd({ settings, BodyEndIslands: BodyEndIslandsStub });
+const DocBodyEnd = createDocBodyEnd({ settings, BodyEndIslands });
 const DocPager = createDocPager({ t });
 
 // ---------------------------------------------------------------------------
@@ -495,7 +521,7 @@ export const VersionsPageView = createVersionsPageView({
     HeadWithDefaults,
     HeaderWithDefaults,
     FooterWithDefaults,
-    BodyEndIslands: BodyEndIslandsStub,
+    BodyEndIslands,
   },
 });
 
@@ -513,15 +539,16 @@ const tagPages = createTagPages({
     HeadWithDefaults,
     HeaderWithDefaults,
     FooterWithDefaults,
-    BodyEndIslands: BodyEndIslandsStub,
+    BodyEndIslands,
     DocHistoryArea: DocHistoryArea as never,
   },
 });
 
 export const { collectTagMapForLocale, TagDetailPageView, TagsIndexPageView } = tagPages;
 
-// Re-export the locale-aware site-tree wrapper for the index entrypoints.
-export { SiteTreeNavWrapper, BodyEndIslandsStub };
+// Re-export the locale-aware site-tree wrapper + the package-default body-end
+// islands for the index entrypoints.
+export { SiteTreeNavWrapper, BodyEndIslands };
 
 // Bring the doc-route-entries builder + types into the chrome surface so the
 // doc entrypoints import a single module.

package/routes-src/_context.ts

@@ -34,6 +34,7 @@
 import { routeContext } from "virtual:zudo-doc-route-context";
 
 import type { Settings } from "@takazudo/zudo-doc/settings";
+import type { ColorScheme } from "@takazudo/zudo-doc/color-scheme-utils";
 import type { FactoryI18n } from "@takazudo/zudo-doc/factory-context";
 import { makeUrlHelpers, type UrlHelpers } from "@takazudo/zudo-doc/url-helpers";
 import {
@@ -84,6 +85,7 @@ export interface RouteContextPayload {
   settings: Settings;
   translations: Record<string, Record<string, string>>;
   tagVocabulary: readonly TagVocabularyEntry[];
+  colorSchemes: Record<string, ColorScheme> | null;
 }
 
 /** The serializable route-context (from the virtual module). */
@@ -91,6 +93,9 @@ export const ctx = routeContext as unknown as RouteContextPayload;
 export const settings: Settings = ctx.settings;
 const translations = ctx.translations;
 const tagVocabulary = ctx.tagVocabulary;
+/** Host color-scheme palette map. `null` when not supplied — `_chrome.tsx`
+ *  falls back to `DEFAULT_SCHEME` in that case. */
+export const colorSchemes: Record<string, ColorScheme> | null = ctx.colorSchemes;
 
 // ---------------------------------------------------------------------------
 // i18n — reconstruct a FactoryI18n from settings + translations (Decision 1).

package/routes-src/_virtual.d.ts

@@ -4,12 +4,16 @@
 // — so this declaration gives the package route entrypoints a typed import.
 //
 // The payload is SERIALIZABLE DATA ONLY (ADR Decision 1): `settings`,
-// `translations`, `tagVocabulary`. `_context.ts` narrows it to the concrete
-// `RouteContextPayload` at the seam.
+// `translations`, `tagVocabulary`, `colorSchemes`. `_context.ts` narrows it
+// to the concrete `RouteContextPayload` at the seam.
 declare module "virtual:zudo-doc-route-context" {
   export const routeContext: {
     settings: unknown;
     translations: Record<string, Record<string, string>>;
     tagVocabulary: ReadonlyArray<Record<string, unknown>>;
+    /** Host color-scheme palette map. `null` when the caller did not pass
+     *  `colorSchemes` to `zudoDocPreset` — `_chrome.tsx` falls back to
+     *  `DEFAULT_SCHEME` in that case. */
+    colorSchemes: Record<string, unknown> | null;
   };
 }

package/routes-src/index.tsx

@@ -28,7 +28,7 @@ import {
   HeadWithDefaults,
   HeaderWithDefaults,
   FooterWithDefaults,
-  BodyEndIslandsStub,
+  BodyEndIslands,
   composeMetaTitle,
 } from "./_chrome.js";
 
@@ -67,7 +67,7 @@ export default function IndexPage(): JSX.Element {
       sidebarOverride={<></>}
       headerOverride={<HeaderWithDefaults lang={locale} currentPath={withBase("/")} />}
       footerOverride={<FooterWithDefaults lang={locale} />}
-      bodyEndComponents={<BodyEndIslandsStub basePath={settings.base ?? "/"} />}
+      bodyEndComponents={<BodyEndIslands basePath={settings.base ?? "/"} />}
       enableClientRouter={settings.dynamicPageTransition}
     >
       <div class="flex justify-center mb-vsp-xl">

package/routes-src/locale-index.tsx

@@ -28,7 +28,7 @@ import {
   HeadWithDefaults,
   HeaderWithDefaults,
   FooterWithDefaults,
-  BodyEndIslandsStub,
+  BodyEndIslands,
   composeMetaTitle,
 } from "./_chrome.js";
 
@@ -83,7 +83,7 @@ export default function LocaleIndexPage({ params }: PageArgs): JSX.Element {
       sidebarOverride={<></>}
       headerOverride={<HeaderWithDefaults lang={locale} currentPath={withBase(`/${locale}/`)} />}
       footerOverride={<FooterWithDefaults lang={locale} />}
-      bodyEndComponents={<BodyEndIslandsStub basePath={settings.base ?? "/"} />}
+      bodyEndComponents={<BodyEndIslands basePath={settings.base ?? "/"} />}
       enableClientRouter={settings.dynamicPageTransition}
     >
       <div class="flex justify-center mb-vsp-xl">