@takazudo/zudo-doc 1.0.2 → 1.2.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/eject/index.js

@@ -49,6 +49,30 @@ const EJECTABLE = {
   details: {
     packageSubpath: "@takazudo/zudo-doc/details",
     localDir: "src/components/zudo-doc/details"
+  },
+  "sidebar-tree-island": {
+    packageSubpath: "@takazudo/zudo-doc/sidebar-tree-island",
+    localDir: "src/components/zudo-doc/sidebar-tree-island"
+  },
+  "sidebar-toggle-island": {
+    packageSubpath: "@takazudo/zudo-doc/sidebar-toggle-island",
+    localDir: "src/components/zudo-doc/sidebar-toggle-island"
+  },
+  "desktop-sidebar-toggle-island": {
+    packageSubpath: "@takazudo/zudo-doc/desktop-sidebar-toggle-island",
+    localDir: "src/components/zudo-doc/desktop-sidebar-toggle-island"
+  },
+  "image-enlarge": {
+    packageSubpath: "@takazudo/zudo-doc/image-enlarge",
+    localDir: "src/components/zudo-doc/image-enlarge"
+  },
+  "doc-history": {
+    packageSubpath: "@takazudo/zudo-doc/doc-history",
+    localDir: "src/components/zudo-doc/doc-history"
+  },
+  "site-tree-nav-island": {
+    packageSubpath: "@takazudo/zudo-doc/site-tree-nav-island",
+    localDir: "src/components/zudo-doc/site-tree-nav-island"
   }
 };
 async function rewireImports(dir) {

package/dist/nav-indexing/doc-card-grid.js

@@ -29,7 +29,7 @@ function DocCardGrid(props) {
           /* @__PURE__ */ jsx(ArrowIcon, {}),
           /* @__PURE__ */ jsx("span", { class: "font-medium text-accent group-hover:underline", children: item.title })
         ] }),
-        item.description && /* @__PURE__ */ jsx("span", { class: "mt-vsp-2xs block text-small text-muted", children: item.description })
+        item.description && /* @__PURE__ */ jsx("span", { class: "mt-vsp-2xs block text-small text-muted group-hover:text-accent group-focus-visible:text-accent", children: item.description })
       ]
     },
     `doc-card-${i}`

package/dist/nav-indexing/nav-card-grid.js

@@ -32,7 +32,7 @@ function NavCardGrid(props) {
           /* @__PURE__ */ jsx(ArrowIcon, {}),
           /* @__PURE__ */ jsx("span", { class: "font-medium text-accent group-hover:underline", children: child.label })
         ] }),
-        child.description && /* @__PURE__ */ jsx("span", { class: "mt-vsp-2xs block text-small text-muted group-hover:underline decoration-muted", children: child.description })
+        child.description && /* @__PURE__ */ jsx("span", { class: "mt-vsp-2xs block text-small text-muted group-hover:text-accent group-hover:underline group-focus-visible:text-accent decoration-muted", children: child.description })
       ]
     },
     `nav-card-${i}`

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,18 +73,23 @@ 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;
     /** Gate for the SSR `/api/ai-chat` injected route (`prerender: false`). */
     aiAssistant?: boolean;
+    /** When `false`, disables zfb's CJK-friendly line-break behaviour.
+     *  Absent means "use the engine default" (currently `true`). */
+    cjkFriendly?: boolean;
 }
 /**
  * The directives recipe map (`markdown.features.directives`): directive name →
@@ -143,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;
@@ -163,6 +182,7 @@ export interface PresetResolveMarkdownLinks {
 }
 export interface PresetMarkdown {
     features: Record<string, boolean | Record<string, unknown>>;
+    cjkFriendly?: boolean;
 }
 export interface PresetCodeHighlight {
     themeLight: string;
@@ -195,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,13 +4,17 @@ function zudoDocPreset({
   buildDocsSchema,
   directiveVocabulary,
   translations,
-  tagVocabulary
+  tagVocabulary,
+  colorSchemes
 }) {
   const docsSchemaJson = z.toJSONSchema(buildDocsSchema());
   return {
     collections: buildCollections(settings, docsSchemaJson),
-    plugins: buildPlugins(settings, { translations, tagVocabulary }),
-    markdown: { features: buildMarkdownFeatures(settings, directiveVocabulary) },
+    plugins: buildPlugins(settings, { translations, tagVocabulary, colorSchemes }),
+    markdown: {
+      features: buildMarkdownFeatures(settings, directiveVocabulary),
+      ...settings.cjkFriendly !== void 0 ? { cjkFriendly: settings.cjkFriendly } : {}
+    },
     // Dual-theme syntect (zfb >= 0.1.0-next.45). Theme names are SYNTECT
     // built-ins, NOT Shiki names. Tokens emit `--shiki-light`/`--shiki-dark`
     // CSS custom properties resolved by the host CSS via `light-dark()`, so
@@ -113,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: {
@@ -133,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

@@ -1,13 +1,13 @@
 /** @jsxRuntime automatic */
 /** @jsxImportSource preact */
-import type { JSX, VNode } from "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;
@@ -25,8 +25,8 @@ export declare const collectTagMapForLocale: (locale: string) => Map<string, imp
     tagInfo: import("../tag-pages/index.js").TagInfo;
 }) => JSX.Element, TagsIndexPageView: (props: {
     locale: string;
-    children?: import("preact").ComponentChildren;
+    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";
@@ -60,6 +62,10 @@ import {
   getThemeDefaultMode as getThemeDefaultModeBase
 } from "../nav-data-prep/index.js";
 import { buildSidebarForSection } from "../sidebar-utils/index.js";
+import { Details } from "../details/index.js";
+import {
+  HtmlPreviewWrapper
+} from "../html-preview-wrapper/index.js";
 const GREY_RAMP = [
   "#000000",
   "#1a1a1a",
@@ -88,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, {});
 }
@@ -98,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(
@@ -189,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,
@@ -270,6 +289,15 @@ const SiteTreeNavWrapper = createSiteTreeNavWrapper({
   groupSatelliteNodes,
   getCategoryOrder
 });
+function HtmlPreviewBound(props) {
+  return HtmlPreviewWrapper({
+    globalConfig: settings.htmlPreview ?? null,
+    ...props
+  });
+}
+function IslandPassthrough(props) {
+  return props.children ?? null;
+}
 function createMdxComponentsBound(lang = defaultLocale) {
   return createMdxComponents({
     settings,
@@ -279,9 +307,22 @@ function createMdxComponentsBound(lang = defaultLocale) {
       CategoryTreeNav: CategoryTreeNavWrapper,
       SiteTreeNav: SiteTreeNavWrapper
     },
-    // PresetGenerator and other showcase-only slots resolve to a package stub
-    // (render nothing) — they are project-bound and not in the package.
+    // Package-owned content components wired here so an INJECTED docs route
+    // (packageOwnedRoutes, no host `pages/` stub) renders MDX using these tags
+    // without the "MDX requires '<X>' to be passed via the 'components' prop"
+    // error (sub-issue #2390 / supersedes #2377).
+    //   - Details      → fully functional (pure <details>, no client JS).
+    //   - HtmlPreview  → SSR-renders; see HtmlPreviewBound for the hydration
+    //                    caveat tied to the node_modules islands-scanner gap.
+    //   - Island       → SSR pass-through; see IslandPassthrough.
+    // PresetGenerator stays a package stub (render nothing): it is the
+    // showcase's project-bound interactive island and downstream projects stub
+    // it. The showcase keeps its host-owned docs catch-all routes (allowlisted)
+    // so its real PresetGenerator still renders.
     extras: {
+      Details,
+      HtmlPreview: HtmlPreviewBound,
+      Island: IslandPassthrough,
       PresetGenerator: (_props) => null
     }
   });
@@ -322,7 +363,7 @@ const VersionsPageView = createVersionsPageView({
     HeadWithDefaults,
     HeaderWithDefaults,
     FooterWithDefaults,
-    BodyEndIslands: BodyEndIslandsStub
+    BodyEndIslands
   }
 });
 const tagPages = createTagPages({
@@ -339,7 +380,7 @@ const tagPages = createTagPages({
     HeadWithDefaults,
     HeaderWithDefaults,
     FooterWithDefaults,
-    BodyEndIslands: BodyEndIslandsStub,
+    BodyEndIslands,
     DocHistoryArea
   }
 });
@@ -348,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: [