@takazudo/zudo-doc 3.2.0 → 4.0.0

package/dist/chrome/derive.d.ts

@@ -4,7 +4,6 @@ import type { JSX, VNode } from "preact";
 import type { ChromeContext, FactoryComponent } from "../factory-context/index.js";
 import type { Settings } from "../settings.js";
 import { type ColorScheme } from "../color-scheme-utils.js";
-import { createBodyEndIslands } from "../doc-body-end-islands/index.js";
 /** Package-default color scheme used when `colorSchemes` is `null` or a key is
  *  missing. Exported so `createChrome` keeps the identical fallback. Base roles
  *  follow the epic's Default Dark defaults on the minimized 5-base ramp
@@ -46,9 +45,22 @@ export declare function deriveSearchWidgetSlot(ctx: ChromeContext): (props: {
     loadingIndexText: string;
     noResultsText: string;
 }) => JSX.Element;
-/** Derive the body-end islands: `ctx.hostBindings.BodyEndIslands` when supplied,
- *  else the package-island subset reconstructed from `settings`. */
-export declare function deriveBodyEndIslands(ctx: ChromeContext): ReturnType<typeof createBodyEndIslands>;
+/**
+ * Derive the body-end islands. The package owns the settings-gated
+ * DesignTokenPanelBootstrap + ThemePackSwitcher mounts even when a host
+ * supplies a BodyEndIslands override; the override is composed with those
+ * package islands rather than replacing them. Without an override,
+ * `createBodyEndIslands` already contains the same package islands, so the
+ * two paths are deliberately exclusive.
+ *
+ * The components default to the statically imported package islands
+ * (#2658 gate-2 fix; #2821), preserving route → chrome → derive → component
+ * scanner reachability for bare `createChrome(routeCtx)` callers. A host may
+ * still replace the DTP component through
+ * `hostBindings.DesignTokenPanelBootstrap`, but the package remains the sole
+ * owner of the mounts and settings gates.
+ */
+export declare function deriveBodyEndIslands(ctx: ChromeContext): (props: import("../doc-body-end-islands/index.js").BodyEndIslandsProps) => JSX.Element;
 /** Derive the DocHistory island: `ctx.hostBindings.DocHistory` when supplied,
  *  else the package no-op stub. */
 export declare function deriveDocHistorySlot(ctx: ChromeContext): typeof DocHistoryStub;

package/dist/chrome/derive.js

@@ -1,4 +1,4 @@
-import { Fragment, jsx } from "preact/jsx-runtime";
+import { Fragment, jsx, jsxs } from "preact/jsx-runtime";
 import { createComposeMetaTitle } from "../compose-meta-title/index.js";
 import {
   generateCssCustomProperties,
@@ -6,6 +6,11 @@ import {
   SEMANTIC_RAMP_DEFAULTS
 } from "../color-scheme-utils.js";
 import { createBodyEndIslands } from "../doc-body-end-islands/index.js";
+import { createDesignTokenPanelIsland } from "../doc-body-end-islands/design-token-panel-island.js";
+import { DesignTokenPanelBootstrap } from "../design-token-panel-bootstrap.js";
+import { ThemePackSwitcher } from "../theme-pack-switcher/index.js";
+import { createThemePackSwitcherIsland } from "../doc-body-end-islands/theme-pack-switcher-island.js";
+import { DEFAULT_THEME_PACK_SLUG } from "../theme-pack-switcher/theme-pack-sync.js";
 import { SearchWidget } from "../search-widget/index.js";
 import { createMdxComponents } from "../mdx-components/index.js";
 import { createCategoryNavWrapper } from "../category-nav/index.js";
@@ -50,7 +55,8 @@ const DEFAULT_SCHEME = {
     fg: { base: 0 },
     selectionBg: { base: 2 },
     selectionFg: { base: 0 },
-    semantic: { ...SEMANTIC_RAMP_DEFAULTS }
+    semantic: { ...SEMANTIC_RAMP_DEFAULTS },
+    syntax: {}
   }
 };
 function DocHistoryStub(_props) {
@@ -64,7 +70,14 @@ function deriveComposeMetaTitle(ctx) {
 }
 function resolveHostScheme(ctx, key) {
   if (!ctx.colorSchemes) return DEFAULT_SCHEME;
-  return ctx.colorSchemes[key] ?? DEFAULT_SCHEME;
+  const scheme = ctx.colorSchemes[key];
+  if (!scheme) {
+    console.warn(
+      `[zudo-doc] color scheme "${key}" not found in the configured colorSchemes \u2014 falling back to the neutral default scheme. Available schemes: ${Object.keys(ctx.colorSchemes).join(", ") || "(none)"}`
+    );
+    return DEFAULT_SCHEME;
+  }
+  return scheme;
 }
 function deriveColorSchemeGenerators(ctx) {
   return {
@@ -138,8 +151,55 @@ function deriveSearchWidgetSlot(ctx) {
   }
   return ctx.hostBindings.SearchWidget ?? SearchWidgetBound;
 }
+function deriveThemePackSwitcherProps(ctx) {
+  const registry = ctx.themePackRegistry;
+  if (registry == null) return null;
+  return {
+    active: ctx.settings.themePack ?? DEFAULT_THEME_PACK_SLUG,
+    order: registry.map((entry) => ({
+      slug: entry.slug,
+      name: entry.meta.name,
+      mode: entry.meta.mode,
+      description: entry.meta.description
+    })),
+    // Base prefix WITH trailing slash — the head-with-defaults themePackBase
+    // convention; the dialog (#2825) concatenates "theme-packs/index.json".
+    base: ctx.withBase("/")
+  };
+}
 function deriveBodyEndIslands(ctx) {
-  return ctx.hostBindings.BodyEndIslands ?? createBodyEndIslands({ settings: ctx.settings });
+  const designTokenPanelDeps = {
+    DesignTokenPanelBootstrap: ctx.hostBindings.DesignTokenPanelBootstrap ?? DesignTokenPanelBootstrap
+  };
+  const themePackSwitcherDeps = {
+    themePackSwitcherProps: deriveThemePackSwitcherProps(ctx),
+    ThemePackSwitcher
+  };
+  const HostBodyEndIslands = ctx.hostBindings.BodyEndIslands;
+  if (!HostBodyEndIslands) {
+    return createBodyEndIslands({
+      settings: ctx.settings,
+      ...designTokenPanelDeps,
+      ...themePackSwitcherDeps
+    });
+  }
+  const DesignTokenPanelIsland = createDesignTokenPanelIsland({
+    designTokenPanel: ctx.settings.designTokenPanel,
+    ...designTokenPanelDeps
+  });
+  const ThemePackSwitcherIsland = createThemePackSwitcherIsland({
+    themePackSwitcher: ctx.settings.themePackSwitcher === true,
+    ...themePackSwitcherDeps
+  });
+  const HostBodyEnd = HostBodyEndIslands;
+  function BodyEndIslands(props) {
+    return /* @__PURE__ */ jsxs(Fragment, { children: [
+      /* @__PURE__ */ jsx(HostBodyEnd, { ...props }),
+      /* @__PURE__ */ jsx(DesignTokenPanelIsland, {}),
+      /* @__PURE__ */ jsx(ThemePackSwitcherIsland, {})
+    ] });
+  }
+  return BodyEndIslands;
 }
 function deriveDocHistorySlot(ctx) {
   return ctx.hostBindings.DocHistory ?? DocHistoryStub;

package/dist/chrome/index.d.ts

@@ -2,6 +2,9 @@
 /** @jsxImportSource preact */
 import type { RouteContext, ChromeHostBindings } from "../factory-context/index.js";
 import type { Settings } from "../settings.js";
+import type { JSX, VNode } from "preact";
+import type { HeaderWithDefaultsProps } from "../header-with-defaults/index.js";
+import type { SidebarWithDefaultsProps } from "../sidebar-with-defaults/index.js";
 /**
  * Build the wired page-chrome factories from a reconstructed route context plus
  * the host-bound slots. Assembles a {@link ChromeContext} (route context +
@@ -12,27 +15,27 @@ import type { Settings } from "../settings.js";
  */
 export declare function createChrome<S extends Settings = Settings>(context: RouteContext<S>, hostBindings?: ChromeHostBindings): {
     composeMetaTitle: (title: string) => string;
-    HeadWithDefaults: (props: import("../head-with-defaults/index.js").HeadWithDefaultsProps) => import("preact").JSX.Element;
-    HeaderWithDefaults: (props: import("../header-with-defaults/index.js").HeaderWithDefaultsProps) => import("preact").JSX.Element;
+    HeadWithDefaults: (props: import("../head-with-defaults/index.js").HeadWithDefaultsProps) => JSX.Element;
+    HeaderWithDefaults: (props: HeaderWithDefaultsProps) => JSX.Element;
     FooterWithDefaults: (props: {
         lang?: string;
-    }) => import("preact").VNode;
-    SidebarWithDefaults: (props: import("../sidebar-with-defaults/index.js").SidebarWithDefaultsProps) => import("preact").JSX.Element;
-    renderDocPage: (props: import("../doc-page-props/index.js").DocPageBaseProps, opts: import("../doc-page-renderer/index.js").RenderDocPageOptions) => import("preact").JSX.Element;
-    VersionsPageView: (props: import("../versions-page/index.js").VersionsPageViewProps) => import("preact").JSX.Element;
+    }) => VNode;
+    SidebarWithDefaults: (props: SidebarWithDefaultsProps) => JSX.Element;
+    renderDocPage: (props: import("../doc-page-props/index.js").DocPageBaseProps, opts: import("../doc-page-renderer/index.js").RenderDocPageOptions) => JSX.Element;
+    VersionsPageView: (props: import("../versions-page/index.js").VersionsPageViewProps) => JSX.Element;
     collectTagMapForLocale: (locale: string) => Map<string, import("../tag-pages/index.js").TagInfo>;
     TagDetailPageView: (props: {
         locale: string;
         tag: string;
         tagInfo: import("../tag-pages/index.js").TagInfo;
-    }) => import("preact").JSX.Element;
+    }) => JSX.Element;
     TagsIndexPageView: (props: {
         locale: string;
         children?: import("preact").ComponentChildren;
-    }) => import("preact").JSX.Element;
+    }) => JSX.Element;
     SiteTreeNavWrapper: import("../factory-context/index.js").FactoryComponent;
-    BodyEndIslands: (props: import("../doc-body-end-islands/index.js").BodyEndIslandsProps) => import("preact").JSX.Element;
-    HomePageView: (props: import("../home-page/index.js").HomePageViewProps) => import("preact").JSX.Element;
+    BodyEndIslands: (props: import("../doc-body-end-islands/index.js").BodyEndIslandsProps) => JSX.Element;
+    HomePageView: (props: import("../home-page/index.js").HomePageViewProps) => JSX.Element;
 };
 /** The wired page-chrome surface returned by {@link createChrome}. */
 export type Chrome = ReturnType<typeof createChrome>;

package/dist/chrome/index.js

@@ -1,7 +1,5 @@
+import { Fragment, jsx } from "preact/jsx-runtime";
 import { createHeadWithDefaults } from "../head-with-defaults/index.js";
-import { createHeaderWithDefaults } from "../header-with-defaults/index.js";
-import { createFooterWithDefaults } from "../footer-with-defaults/index.js";
-import { createSidebarWithDefaults } from "../sidebar-with-defaults/index.js";
 import { createRenderDocPage } from "../doc-page-renderer/index.js";
 import { createVersionsPageView } from "../versions-page/index.js";
 import { createTagPages } from "../tag-pages/index.js";
@@ -11,14 +9,22 @@ import {
   deriveBodyEndIslands,
   deriveMdxComponents
 } from "./derive.js";
+import { derivePrimaryChromeSlots } from "./primary-slots.js";
 function createChrome(context, hostBindings = {}) {
   const components = {};
   const ctx = { ...context, components, hostBindings };
   const composeMetaTitle = deriveComposeMetaTitle(ctx);
   const HeadWithDefaults = createHeadWithDefaults(ctx);
-  const HeaderWithDefaults = createHeaderWithDefaults(ctx);
-  const FooterWithDefaults = createFooterWithDefaults(ctx);
-  const SidebarWithDefaults = createSidebarWithDefaults(ctx);
+  const primary = derivePrimaryChromeSlots(ctx);
+  const HeaderWithDefaults = (props) => /* @__PURE__ */ jsx(Fragment, { children: primary.Header({ ...props, lang: props.lang ?? context.defaultLocale }) });
+  const FooterWithDefaults = (props) => /* @__PURE__ */ jsx(Fragment, { children: primary.Footer({ lang: props.lang ?? context.defaultLocale }) });
+  const SidebarWithDefaults = (props) => /* @__PURE__ */ jsx(Fragment, { children: primary.Sidebar({
+    currentSlug: props.currentSlug ?? "",
+    lang: props.lang ?? context.defaultLocale,
+    navSection: props.navSection,
+    currentVersion: props.currentVersion,
+    currentPath: props.currentPath ?? ""
+  }) });
   const renderDocPage = createRenderDocPage(ctx);
   const VersionsPageView = createVersionsPageView(ctx);
   const { collectTagMapForLocale, TagDetailPageView, TagsIndexPageView } = createTagPages(ctx);

package/dist/chrome/primary-slots.d.ts

@@ -0,0 +1,21 @@
+/** @jsxRuntime automatic */
+/** @jsxImportSource preact */
+import type { ComponentChildren } from "preact";
+import type { ChromeContext } from "../factory-context/index.js";
+import type { BreadcrumbSlotProps, DocPagerSlotProps, FooterSlotProps, HeaderSlotProps, SidebarSlotProps, TocSlotProps } from "../chrome-bindings.js";
+import type { Settings } from "../settings.js";
+type PrimarySlot<P> = (props: P) => ComponentChildren;
+/**
+ * Resolve all six primary chrome components through one binding object.
+ * Accessors keep package defaults lazy: a home view that only reads Header and
+ * Footer does not construct the doc-only Sidebar or DocPager factories.
+ */
+export declare function derivePrimaryChromeSlots<S extends Settings = Settings>(ctx: ChromeContext<S>): {
+    readonly Header: PrimarySlot<HeaderSlotProps>;
+    readonly Footer: PrimarySlot<FooterSlotProps>;
+    readonly Sidebar: PrimarySlot<SidebarSlotProps>;
+    readonly Toc: PrimarySlot<TocSlotProps>;
+    readonly Breadcrumb: PrimarySlot<BreadcrumbSlotProps>;
+    readonly DocPager: PrimarySlot<DocPagerSlotProps>;
+};
+export {};

package/dist/chrome/primary-slots.js

@@ -0,0 +1,59 @@
+import { createHeaderWithDefaults } from "../header-with-defaults/index.js";
+import { createFooterWithDefaults } from "../footer-with-defaults/index.js";
+import { createSidebarWithDefaults } from "../sidebar-with-defaults/index.js";
+import { Toc } from "../toc/index.js";
+import { Breadcrumb } from "../breadcrumb/index.js";
+import { createDocPager } from "../doc-pager/index.js";
+function resolvePrimarySlot(slot, replacement, createPackageDefault) {
+  if (replacement !== void 0 && typeof replacement !== "function") {
+    throw new TypeError(
+      `Invalid primary chrome replacement at chromeBindings.${slot}: expected a callable component. Export ${slot} from the object built with defineChromeBindings() and point settings.chromeBindingsModule at that module.`
+    );
+  }
+  return replacement ? replacement : createPackageDefault();
+}
+function derivePrimaryChromeSlots(ctx) {
+  return {
+    get Header() {
+      return resolvePrimarySlot(
+        "Header",
+        ctx.hostBindings.Header,
+        () => createHeaderWithDefaults(ctx)
+      );
+    },
+    get Footer() {
+      return resolvePrimarySlot(
+        "Footer",
+        ctx.hostBindings.Footer,
+        () => createFooterWithDefaults(ctx)
+      );
+    },
+    get Sidebar() {
+      return resolvePrimarySlot(
+        "Sidebar",
+        ctx.hostBindings.Sidebar,
+        () => createSidebarWithDefaults(ctx)
+      );
+    },
+    get Toc() {
+      return resolvePrimarySlot("Toc", ctx.hostBindings.Toc, () => Toc);
+    },
+    get Breadcrumb() {
+      return resolvePrimarySlot(
+        "Breadcrumb",
+        ctx.hostBindings.Breadcrumb,
+        () => Breadcrumb
+      );
+    },
+    get DocPager() {
+      return resolvePrimarySlot(
+        "DocPager",
+        ctx.hostBindings.DocPager,
+        () => createDocPager(ctx)
+      );
+    }
+  };
+}
+export {
+  derivePrimaryChromeSlots
+};

package/dist/chrome-bindings.d.ts

@@ -0,0 +1,227 @@
+import type { ComponentChildren } from "preact";
+import type { BreadcrumbItem } from "./breadcrumb/index.js";
+import type { DocPageNavNode } from "./doc-page-shell/index.js";
+import type { HeadingItem } from "./toc/index.js";
+import type { ChromeHostBindings } from "./factory-context/index.js";
+import type { HeaderRightComponentRegistry } from "./header/types.js";
+/**
+ * Props the header passes to the `SearchWidget` slot — the 7 locale-aware
+ * strings from `header-with-defaults`'s `<SearchWidget … />` render (via
+ * `deriveSearchWidgetSlot`'s `SearchWidgetBound`, `chrome/derive.tsx`). NOTE
+ * the package's own `SearchWidget` also takes `base`, but the chrome binds that
+ * internally — a host-supplied widget is called with these 7 props ONLY, so
+ * requiring `base` here would (correctly) be drift.
+ */
+export interface SearchWidgetSlotProps {
+    placeholderText: string;
+    shortcutHint: string;
+    resultCountTemplate: string;
+    searchLabel: string;
+    searchUnavailableText: string;
+    loadingIndexText: string;
+    noResultsText: string;
+}
+/**
+ * Props the chrome passes to the `BodyEndIslands` slot — matches
+ * `BodyEndIslandsProps` (`doc-body-end-islands`); called as
+ * `<BodyEndIslands basePath={…} />` in `home-page` / `doc-body-end`.
+ */
+export interface BodyEndIslandsSlotProps {
+    basePath: string;
+    aiChatBodyLabel?: string;
+}
+/**
+ * Props the chrome passes to the `DocHistory` island slot — matches
+ * `DocHistoryProps` (`doc-history/index.tsx`) / `DocHistoryComponent`
+ * (`doc-history-area`), rendered as
+ * `<DocHistory slug=… locale=… basePath=… />`.
+ */
+export interface DocHistorySlotProps {
+    slug: string;
+    locale?: string;
+    basePath?: string;
+}
+/**
+ * Props the chrome passes to the `DesignTokenPanelBootstrap` slot — NONE. It is
+ * rendered as `<DesignTokenPanelBootstrap />` (zero props) inside
+ * `createBodyEndIslands`. An empty object type (no index signature) so a
+ * zero-prop or all-optional-prop component is accepted while a component that
+ * REQUIRES any prop is drift.
+ */
+export type DesignTokenPanelBootstrapSlotProps = Record<never, never>;
+/**
+ * One footer tag entry the `loadTagsForLocale` result is read for —
+ * `footer-with-defaults` maps over the array reading `{ tag, count }`. The
+ * return contract is a `readonly` array of these (extra per-entry fields, e.g.
+ * the `docs` on `collectTags`' `TagInfo`, are allowed — a supertype element).
+ */
+export interface FooterTagEntry {
+    tag: string;
+    count: number;
+}
+/**
+ * Props the chrome passes to each `frontmatterRenderers[key]` renderer —
+ * mirrors `FrontmatterCellRendererProps` at the real call site
+ * (`metainfo/frontmatter-preview.tsx`: `rendererFn({ value, entryKey, data,
+ * locale })`). A provided renderer's parameter must be a SUPERTYPE of this (it
+ * may read a subset), so a renderer REQUIRING a prop the chrome never passes is
+ * a compile error — the #2674 drift check this slot would otherwise erase.
+ */
+export interface FrontmatterRendererSlotProps {
+    value: NonNullable<unknown>;
+    entryKey: string;
+    data: Record<string, unknown>;
+    locale?: string;
+}
+/**
+ * Props supplied at every package `Header` replacement call site. `lang` is
+ * always present; the remaining fields are route-specific.
+ */
+export interface HeaderSlotProps {
+    lang: string;
+    currentPath?: string;
+    currentVersion?: string;
+    currentSlug?: string;
+    navSection?: string;
+}
+/** Props supplied at every package `Footer` replacement call site. */
+export interface FooterSlotProps {
+    lang: string;
+}
+/**
+ * Props supplied to the doc-route `Sidebar` replacement. Properties whose
+ * values may be absent remain present with `undefined`, matching the real JSX
+ * call site.
+ */
+export interface SidebarSlotProps {
+    currentSlug: string;
+    lang: string;
+    navSection: string | undefined;
+    currentVersion: string | undefined;
+    currentPath: string;
+}
+/** Props supplied to the desktop `Toc` replacement. */
+export interface TocSlotProps {
+    headings: readonly HeadingItem[];
+    title: string;
+}
+/**
+ * Props supplied to `Breadcrumb` replacements. All package call sites provide
+ * pre-built items; doc routes additionally provide the optional right slot.
+ */
+export interface BreadcrumbSlotProps {
+    items: BreadcrumbItem[];
+    rightSlot?: ComponentChildren;
+}
+/** Props supplied to the doc-route `DocPager` replacement. */
+export interface DocPagerSlotProps {
+    prev: DocPageNavNode | null;
+    next: DocPageNavNode | null;
+    locale: string;
+}
+/**
+ * The compile-time-checked input for {@link defineChromeBindings}. See the
+ * module header for the drift-detection rationale.
+ */
+export interface ChromeBindingsInput {
+    /** Primary header replacement — see {@link HeaderSlotProps}. */
+    Header?: (props: HeaderSlotProps) => unknown;
+    /** Primary footer replacement — see {@link FooterSlotProps}. */
+    Footer?: (props: FooterSlotProps) => unknown;
+    /** Primary doc-sidebar replacement — see {@link SidebarSlotProps}. */
+    Sidebar?: (props: SidebarSlotProps) => unknown;
+    /** Primary desktop TOC replacement — see {@link TocSlotProps}. */
+    Toc?: (props: TocSlotProps) => unknown;
+    /** Primary breadcrumb replacement — see {@link BreadcrumbSlotProps}. */
+    Breadcrumb?: (props: BreadcrumbSlotProps) => unknown;
+    /** Primary previous/next pager replacement — see {@link DocPagerSlotProps}. */
+    DocPager?: (props: DocPagerSlotProps) => unknown;
+    /** Header search widget — see {@link SearchWidgetSlotProps}. */
+    SearchWidget?: (props: SearchWidgetSlotProps) => unknown;
+    /**
+     * Named header-right renderers. Values are callable-only and receive the
+     * exact `HeaderRightComponentProps` used by the header renderer.
+     */
+    headerRightComponents?: HeaderRightComponentRegistry;
+    /** Body-end bootstrap islands — see {@link BodyEndIslandsSlotProps}. */
+    BodyEndIslands?: (props: BodyEndIslandsSlotProps) => unknown;
+    /** DocHistory island — see {@link DocHistorySlotProps}. */
+    DocHistory?: (props: DocHistorySlotProps) => unknown;
+    /** Design-token-panel bootstrap island — see {@link DesignTokenPanelBootstrapSlotProps}. */
+    DesignTokenPanelBootstrap?: (props: DesignTokenPanelBootstrapSlotProps) => unknown;
+    /**
+     * Per-page git-history meta manifest (data slot). Read as
+     * `Record<string, DocHistoryMetaEntry>` inside `doc-metainfo-area` /
+     * `doc-history-area`; the loose `Record<string, unknown>` is the boundary shape.
+     */
+    docHistoryMeta?: Record<string, unknown>;
+    /**
+     * Sidebar section config (opaque data blob — the chrome casts it to `never`
+     * before handing it to `buildSidebarForSection`). Typed `object` NOT
+     * `Record<string, unknown>` on purpose: a concrete interface-typed sidebars
+     * object (no index signature) must be accepted WITHOUT a cast.
+     */
+    sidebarsConfig?: object;
+    /** Footer tag vocabulary (data slot); read structurally by `footer-with-defaults`. */
+    tagVocabulary?: readonly unknown[];
+    /**
+     * Frontmatter preview renderers keyed by field (renderer record). Each value
+     * must be callable with {@link FrontmatterRendererSlotProps} (the fixed
+     * package call-side contract), so a non-function or a renderer requiring an
+     * unpassed prop is a compile error. Narrow-props renderers still work
+     * (parameter contravariance). Unlike `mdxExtras`, this slot has a fixed call
+     * site, so it carries the real contract rather than a loose `Record`.
+     */
+    frontmatterRenderers?: Record<string, (props: FrontmatterRendererSlotProps) => unknown>;
+    /**
+     * MDX content-component overrides (renderer record). Same loose value type as
+     * `frontmatterRenderers`; the showcase's `MdxStub = (_props: unknown) => null`
+     * is accepted deliberately (`unknown` props are a safe supertype).
+     */
+    mdxExtras?: Record<string, unknown>;
+    /**
+     * Frontmatter preview entry builder. `doc-content-header` calls it with the
+     * page `data` (`Record<string, unknown>`) and spreads the result into
+     * `<FrontmatterPreview entries={…} />`, which destructures each entry as
+     * `[key, value]` — so the return must be an array of `[string, unknown]`
+     * tuples, not merely an array.
+     */
+    buildFrontmatterPreviewEntries?: (data: Record<string, unknown>) => readonly (readonly [string, unknown])[];
+    /**
+     * Footer tag-list loader. `footer-with-defaults` calls it with the locale and
+     * maps the result reading `{ tag, count }` — see {@link FooterTagEntry}.
+     * A wrong return type (e.g. a non-array) is a compile error.
+     */
+    loadTagsForLocale?: (lang: string) => readonly FooterTagEntry[];
+    /**
+     * Extra content rendered inside the doc content header. An arg-object
+     * RENDERER — the `ChromeHostBindings` type is already call-side-precise, so
+     * reuse it verbatim (no widening friction).
+     */
+    docContentHeaderExtras?: ChromeHostBindings["docContentHeaderExtras"];
+    /**
+     * Extra content rendered in the home hero. An arg-object RENDERER — reuse the
+     * already call-side-precise `ChromeHostBindings` type verbatim.
+     */
+    homeExtras?: ChromeHostBindings["homeExtras"];
+}
+/**
+ * Reject unknown slot names. Generic inference (below) turns OFF the
+ * excess-property check that a plain `input: ChromeBindingsInput` parameter
+ * would get for an object literal, so re-impose it explicitly: any key of `T`
+ * that is NOT a `ChromeBindingsInput` slot is mapped to `never`, making a real
+ * value for it fail to assign.
+ */
+type NoExtraKeys<T> = ChromeBindingsInput & Record<Exclude<keyof T, keyof ChromeBindingsInput>, never>;
+/**
+ * Widen a compile-time-checked host bindings object to `ChromeHostBindings`.
+ *
+ * The generic `T` captures the caller's exact object so {@link NoExtraKeys}
+ * can reject unknown slot names; `T extends ChromeBindingsInput` enforces every
+ * slot's per-call-site contract (a component requiring a prop the chrome never
+ * passes, or a function slot with an incompatible return type, is a COMPILE
+ * ERROR). Runtime behaviour is pure PASS-THROUGH — the returned object IS the
+ * input.
+ */
+export declare function defineChromeBindings<T extends ChromeBindingsInput>(input: T & NoExtraKeys<T>): ChromeHostBindings;
+export {};

package/dist/chrome-bindings.js

@@ -0,0 +1,6 @@
+function defineChromeBindings(input) {
+  return input;
+}
+export {
+  defineChromeBindings
+};

package/dist/code-syntax/code-block-enhancer-script.d.ts

@@ -1 +1,5 @@
+/** Highlighted blocks emitted by the current class-mode highlighter. */
+export declare const HIGHLIGHTED_CODE_BLOCK_SELECTOR = "pre.hi-root";
+/** Highlighted blocks plus the intentional raw-code fallback inside tabs. */
+export declare const CODE_BLOCK_ENHANCER_SELECTOR = "pre.hi-root, .tab-panel pre";
 export declare const CODE_BLOCK_ENHANCER_SCRIPT: string;

package/dist/code-syntax/code-block-enhancer-script.js

@@ -2,6 +2,8 @@ import {
   AFTER_NAVIGATE_EVENT,
   BEFORE_NAVIGATE_EVENT
 } from "../transitions/page-events.js";
+const HIGHLIGHTED_CODE_BLOCK_SELECTOR = "pre.hi-root";
+const CODE_BLOCK_ENHANCER_SELECTOR = `${HIGHLIGHTED_CODE_BLOCK_SELECTOR}, .tab-panel pre`;
 const CODE_BLOCK_ENHANCER_SCRIPT = `(function () {
   // Single shared ResizeObserver for all code blocks on the page.
   var wrapButtons = new Map();
@@ -14,15 +16,14 @@ const CODE_BLOCK_ENHANCER_SCRIPT = `(function () {
 
   function enhanceCodeBlocks() {
     // Selector covers two shapes:
-    //   1. pre.syntect-... from the syntect highlighter (the class
-    //      is anchored or merged with other classes).
+    //   1. pre.hi-root from the class-mode highlighter.
     //   2. bare pre inside .tab-panel (TabItem) wrappers where some
     //      pipelines emit class-less pre elements.
     // No backticks in this comment: this whole script body lives inside
     // a template literal in the host .ts module, so an inline backtick
     // would close the literal and make 'panel' a free identifier.
     var pres = document.querySelectorAll(
-      'pre[class*="syntect-"], .tab-panel pre',
+      ${JSON.stringify(CODE_BLOCK_ENHANCER_SELECTOR)},
     );
 
     for (var pi = 0; pi < pres.length; pi++) {
@@ -161,5 +162,7 @@ const CODE_BLOCK_ENHANCER_SCRIPT = `(function () {
   document.addEventListener(${JSON.stringify(AFTER_NAVIGATE_EVENT)}, enhanceCodeBlocks);
 })();`;
 export {
-  CODE_BLOCK_ENHANCER_SCRIPT
+  CODE_BLOCK_ENHANCER_SCRIPT,
+  CODE_BLOCK_ENHANCER_SELECTOR,
+  HIGHLIGHTED_CODE_BLOCK_SELECTOR
 };

package/dist/code-syntax/code-block-enhancer.d.ts

@@ -8,7 +8,8 @@ import type { JSX } from "preact";
  * and emits the code-block enhancer init script via `dangerouslySetInnerHTML`.
  *
  * The script:
- * - Wraps each `<pre class="syntect-*">` in a `.code-block-wrapper` container.
+ * - Wraps each highlighted `<pre>` (`.hi-root`) and raw tab-panel fallback in
+ *   a `.code-block-wrapper` container.
  * - Adds a copy-to-clipboard button and a word-wrap toggle button.
  * - Observes resize events to hide the wrap button when content fits.
  * - Handles before-navigate cleanup and after-navigate re-init for View
@@ -16,4 +17,3 @@ import type { JSX } from "preact";
  *   `AFTER_NAVIGATE_EVENT` in `../transitions/page-events.ts`.
  */
 export declare function CodeBlockEnhancer(): JSX.Element;
-export default CodeBlockEnhancer;

package/dist/code-syntax/code-block-enhancer.js

@@ -6,8 +6,6 @@ function CodeBlockEnhancer() {
     /* @__PURE__ */ jsx("script", { dangerouslySetInnerHTML: { __html: CODE_BLOCK_ENHANCER_SCRIPT } })
   ] });
 }
-var code_block_enhancer_default = CodeBlockEnhancer;
 export {
-  CodeBlockEnhancer,
-  code_block_enhancer_default as default
+  CodeBlockEnhancer
 };

package/dist/code-syntax/index.d.ts

@@ -1,9 +1,9 @@
-export { CodeBlockEnhancer, default as CodeBlockEnhancerDefault } from "./code-block-enhancer.js";
+export { CodeBlockEnhancer } from "./code-block-enhancer.js";
 export { CODE_BLOCK_ENHANCER_SCRIPT } from "./code-block-enhancer-script.js";
-export { MermaidInit, default as MermaidInitDefault, } from "./mermaid-init.js";
+export { MermaidInit } from "./mermaid-init.js";
 export type { MermaidInitProps } from "./mermaid-init.js";
-export { MERMAID_INIT_SCRIPT, MERMAID_CDN_MODULE_URL, buildMermaidInitScript, } from "./mermaid-init-script.js";
-export { Tabs, default as TabsDefault } from "./tabs.js";
+export { MERMAID_CDN_MODULE_URL, buildMermaidInitScript, } from "./mermaid-init-script.js";
+export { Tabs } from "./tabs.js";
 export type { TabsProps } from "./tabs.js";
-export { TabsInit, default as TabsInitDefault } from "./tabs-init.js";
+export { TabsInit } from "./tabs-init.js";
 export { TABS_INIT_SCRIPT } from "./tabs-init-script.js";

package/dist/code-syntax/index.js

@@ -1,29 +1,20 @@
-import { CodeBlockEnhancer, default as default2 } from "./code-block-enhancer.js";
+import { CodeBlockEnhancer } from "./code-block-enhancer.js";
 import { CODE_BLOCK_ENHANCER_SCRIPT } from "./code-block-enhancer-script.js";
+import { MermaidInit } from "./mermaid-init.js";
 import {
-  MermaidInit,
-  default as default3
-} from "./mermaid-init.js";
-import {
-  MERMAID_INIT_SCRIPT,
   MERMAID_CDN_MODULE_URL,
   buildMermaidInitScript
 } from "./mermaid-init-script.js";
-import { Tabs, default as default4 } from "./tabs.js";
-import { TabsInit, default as default5 } from "./tabs-init.js";
+import { Tabs } from "./tabs.js";
+import { TabsInit } from "./tabs-init.js";
 import { TABS_INIT_SCRIPT } from "./tabs-init-script.js";
 export {
   CODE_BLOCK_ENHANCER_SCRIPT,
   CodeBlockEnhancer,
-  default2 as CodeBlockEnhancerDefault,
   MERMAID_CDN_MODULE_URL,
-  MERMAID_INIT_SCRIPT,
   MermaidInit,
-  default3 as MermaidInitDefault,
   TABS_INIT_SCRIPT,
   Tabs,
-  default4 as TabsDefault,
   TabsInit,
-  default5 as TabsInitDefault,
   buildMermaidInitScript
 };