npm - @takazudo/zudo-doc - Versions diffs - 3.2.0 → 4.0.0 - Mend

@takazudo/zudo-doc 3.2.0 → 4.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (439) hide show

package/dist/doclayout/doc-layout.d.ts CHANGED Viewed

@@ -12,6 +12,14 @@ export interface DocLayoutHtmlAttrs {
      * Set per `<html>`-level color-scheme strategy.
      */
     dataTheme?: string;
+    /**
+     * Optional `data-theme-pack` attribute value — the CONFIGURED theme-pack
+     * slug (ADR `docs/adr/theme-packs.md`, Decision 3 DOM contract, #2822).
+     * Unlike `data-theme` (user-preference-only, client-set) the configured
+     * pack is build-static, so SSR can and must emit it for the no-JS path;
+     * the pre-paint bootstrap re-asserts the user's persisted slug on load.
+     */
+    dataThemePack?: string;
     /**
      * Optional inline `style` value to apply to `<html>` — in practice this
      * is `color-scheme: light` / `color-scheme: dark`.

package/dist/doclayout/doc-layout.js CHANGED Viewed

@@ -8,6 +8,7 @@ function DocLayout(props) {
     noindex,
     lang = "en",
     dataTheme,
+    dataThemePack,
     htmlStyle,
     head,
     header,
@@ -35,6 +36,9 @@ function DocLayout(props) {
   if (dataTheme !== void 0) {
     htmlAttrs["data-theme"] = dataTheme;
   }
+  if (dataThemePack !== void 0) {
+    htmlAttrs["data-theme-pack"] = dataThemePack;
+  }
   if (htmlStyle !== void 0) {
     htmlAttrs.style = htmlStyle;
   }
@@ -46,7 +50,12 @@ function DocLayout(props) {
       description !== void 0 && /* @__PURE__ */ jsx("meta", { name: "description", content: description }),
       noindex && /* @__PURE__ */ jsx("meta", { name: "robots", content: "noindex, nofollow" }),
       enableClientRouter !== false ? ClientRouter({
-        preserveHtmlAttrs: ["data-sidebar-hidden", "data-theme", "style"]
+        preserveHtmlAttrs: [
+          "data-sidebar-hidden",
+          "data-theme",
+          "data-theme-pack",
+          "style"
+        ]
       }) : null,
       head
     ] }),

package/dist/docs-schema/index.d.ts ADDED Viewed

@@ -0,0 +1,67 @@
+/**
+ * Default docs-frontmatter zod schema builder.
+ *
+ * Ported (and parameterized) from the `create-zudo-doc` base template's
+ * `src/config/docs-schema.ts` `buildDocsSchema` export (epic
+ * zudolab/zudo-doc#2651, S4 #2654).
+ *
+ * Unlike the template original — which read the host `settings` and
+ * `tag-vocabulary` singletons directly — this package default NEVER imports
+ * host singletons: governance mode and the vocabulary entries are passed in
+ * as `opts`. `zudoDoc()` (#2657) calls this with the project's merged
+ * governance config; a project may also override `buildDocsSchema` entirely
+ * via `ZudoDocConfig.buildDocsSchema`.
+ */
+import { z } from "zod";
+import type { PresetTagVocabularyEntry } from "../preset.js";
+export interface BuildDocsSchemaOptions {
+    tagGovernance?: "off" | "warn" | "strict";
+    tagVocabulary?: readonly PresetTagVocabularyEntry[];
+}
+/**
+ * Build the docs frontmatter zod schema.
+ *
+ * Returns a single `z.object(...).passthrough()` reused for every docs
+ * collection (default + per-locale + per-version + per-version-per-locale).
+ * The `tags` field is governance-aware: `buildTagsSchema()` returns a plain
+ * `z.array(z.string())` when governance is off (or `opts` is omitted), or a
+ * restricted `z.enum` when `opts.tagGovernance: "strict"` plus a non-empty
+ * `opts.tagVocabulary` is supplied.
+ *
+ * `.passthrough()` keeps custom frontmatter keys (e.g. `author`, `status`)
+ * available downstream — the frontmatter-preview UI relies on this to
+ * surface arbitrary keys without declaring each one here.
+ */
+export declare function buildDocsSchema(opts?: BuildDocsSchemaOptions): z.ZodObject<{
+    title: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    category: z.ZodOptional<z.ZodString>;
+    sidebar_position: z.ZodOptional<z.ZodNumber>;
+    sidebar_label: z.ZodOptional<z.ZodString>;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString>> | z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        [x: string]: string;
+    }>>>;
+    search_exclude: z.ZodOptional<z.ZodBoolean>;
+    pagination_next: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    pagination_prev: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    draft: z.ZodOptional<z.ZodBoolean>;
+    unlisted: z.ZodOptional<z.ZodBoolean>;
+    hide_sidebar: z.ZodOptional<z.ZodBoolean>;
+    hide_toc: z.ZodOptional<z.ZodBoolean>;
+    wide: z.ZodOptional<z.ZodBoolean>;
+    doc_history: z.ZodOptional<z.ZodBoolean>;
+    standalone: z.ZodOptional<z.ZodBoolean>;
+    slug: z.ZodOptional<z.ZodString>;
+    generated: z.ZodOptional<z.ZodBoolean>;
+    category_no_page: z.ZodOptional<z.ZodBoolean>;
+    category_sort_order: z.ZodOptional<z.ZodEnum<{
+        asc: "asc";
+        desc: "desc";
+    }>>;
+}, z.core.$loose>;
+/**
+ * TypeScript type inferred from the default docs frontmatter zod schema.
+ * A project overriding `buildDocsSchema` via `ZudoDocConfig` should derive
+ * its own `DocsData` type from its own builder instead of this one.
+ */
+export type DocsData = z.infer<ReturnType<typeof buildDocsSchema>>;

package/dist/docs-schema/index.js ADDED Viewed

@@ -0,0 +1,43 @@
+import { z } from "zod";
+function buildTagsSchema(opts) {
+  const vocabulary = opts?.tagVocabulary ?? [];
+  const vocabularyActive = vocabulary.length > 0 && opts?.tagGovernance === "strict";
+  if (!vocabularyActive) return z.array(z.string()).optional();
+  const allowed = new Set(vocabulary.map((entry) => entry.id));
+  const allowedList = [...allowed];
+  if (allowedList.length === 0) return z.array(z.string()).optional();
+  const [first, ...rest] = allowedList;
+  return z.array(z.enum([first, ...rest])).optional();
+}
+function buildDocsSchema(opts) {
+  return z.object({
+    title: z.string(),
+    description: z.string().optional(),
+    category: z.string().optional(),
+    sidebar_position: z.number().optional(),
+    sidebar_label: z.string().optional(),
+    tags: buildTagsSchema(opts),
+    search_exclude: z.boolean().optional(),
+    pagination_next: z.string().nullable().optional(),
+    pagination_prev: z.string().nullable().optional(),
+    draft: z.boolean().optional(),
+    unlisted: z.boolean().optional(),
+    hide_sidebar: z.boolean().optional(),
+    hide_toc: z.boolean().optional(),
+    wide: z.boolean().optional(),
+    doc_history: z.boolean().optional(),
+    standalone: z.boolean().optional(),
+    slug: z.string().optional(),
+    generated: z.boolean().optional(),
+    // Category metadata expressed as a directory index.mdx's frontmatter — the
+    // frontmatter form of `_category_.json`. `category_no_page` makes the index
+    // a non-linked sidebar header excluded from routes/sitemap/search;
+    // `category_sort_order` sets the child sort direction. Frontmatter wins
+    // over the sidecar.
+    category_no_page: z.boolean().optional(),
+    category_sort_order: z.enum(["asc", "desc"]).optional()
+  }).passthrough();
+}
+export {
+  buildDocsSchema
+};

package/dist/eject/index.d.ts CHANGED Viewed

@@ -1,8 +1,24 @@
+export type PrimaryChromeSlot = "Header" | "Footer" | "Sidebar" | "Toc" | "Breadcrumb" | "DocPager";
+export type EjectableClassification = {
+    kind: "primary";
+    /** The matching primary replacement key in `ChromeHostBindings`. */
+    slot: PrimaryChromeSlot;
+} | {
+    kind: "nested";
+    /** Exact supported binding or owner-replacement instructions. */
+    remediation: string;
+} | {
+    kind: "content";
+    /** Exact project-owned MDX registration instructions. */
+    remediation: string;
+};
 export interface EjectableEntry {
     /** Package subpath, e.g. `@takazudo/zudo-doc/header` */
     packageSubpath: string;
     /** Local destination dir, project-relative POSIX (no trailing slash) */
     localDir: string;
+    /** Static rendering/binding class. Never infer this from host call sites. */
+    classification: EjectableClassification;
 }
 export declare const EJECTABLE: Record<string, EjectableEntry>;
 export interface ZudoDocJson {

package/dist/eject/index.js CHANGED Viewed

@@ -4,77 +4,171 @@ import pc from "picocolors";
 const EJECTABLE = {
   header: {
     packageSubpath: "@takazudo/zudo-doc/header",
-    localDir: "src/components/zudo-doc/header"
+    localDir: "src/components/zudo-doc/header",
+    classification: { kind: "primary", slot: "Header" }
   },
   footer: {
     packageSubpath: "@takazudo/zudo-doc/footer",
-    localDir: "src/components/zudo-doc/footer"
+    localDir: "src/components/zudo-doc/footer",
+    classification: { kind: "primary", slot: "Footer" }
   },
   breadcrumb: {
     packageSubpath: "@takazudo/zudo-doc/breadcrumb",
-    localDir: "src/components/zudo-doc/breadcrumb"
+    localDir: "src/components/zudo-doc/breadcrumb",
+    classification: { kind: "primary", slot: "Breadcrumb" }
   },
   toc: {
     packageSubpath: "@takazudo/zudo-doc/toc",
-    localDir: "src/components/zudo-doc/toc"
+    localDir: "src/components/zudo-doc/toc",
+    classification: { kind: "primary", slot: "Toc" }
   },
   sidebar: {
     packageSubpath: "@takazudo/zudo-doc/sidebar",
-    localDir: "src/components/zudo-doc/sidebar"
+    localDir: "src/components/zudo-doc/sidebar",
+    classification: { kind: "primary", slot: "Sidebar" }
   },
   "theme-toggle": {
     packageSubpath: "@takazudo/zudo-doc/theme-toggle",
-    localDir: "src/components/zudo-doc/theme-toggle"
+    localDir: "src/components/zudo-doc/theme-toggle",
+    classification: {
+      kind: "nested",
+      remediation: 'Register the local ThemeToggle under a new name in chromeBindings.headerRightComponents, then use that same name in settings.headerRightItems. The built-in name "theme-toggle" is reserved.'
+    }
   },
   "page-loading": {
     packageSubpath: "@takazudo/zudo-doc/page-loading",
-    localDir: "src/components/zudo-doc/page-loading"
+    localDir: "src/components/zudo-doc/page-loading",
+    classification: {
+      kind: "nested",
+      remediation: "Replace chromeBindings.BodyEndIslands with a project-owned composition that imports the local PageLoadingOverlay."
+    }
   },
   "tab-item": {
     packageSubpath: "@takazudo/zudo-doc/tab-item",
-    localDir: "src/components/zudo-doc/tab-item"
+    localDir: "src/components/zudo-doc/tab-item",
+    classification: {
+      kind: "content",
+      remediation: "Set chromeBindings.mdxExtras.TabItem to the local TabItem."
+    }
   },
   "doc-pager": {
     packageSubpath: "@takazudo/zudo-doc/doc-pager",
-    localDir: "src/components/zudo-doc/doc-pager"
+    localDir: "src/components/zudo-doc/doc-pager",
+    classification: { kind: "primary", slot: "DocPager" }
   },
   "content-admonition": {
     packageSubpath: "@takazudo/zudo-doc/content-admonition",
-    localDir: "src/components/zudo-doc/content-admonition"
+    localDir: "src/components/zudo-doc/content-admonition",
+    classification: {
+      kind: "content",
+      remediation: "Create the local admonition renderers with makeAdmonition, then set the matching chromeBindings.mdxExtras keys (Note, Tip, Info, Warning, and Danger)."
+    }
   },
   "code-group": {
     packageSubpath: "@takazudo/zudo-doc/code-group",
-    localDir: "src/components/zudo-doc/code-group"
+    localDir: "src/components/zudo-doc/code-group",
+    classification: {
+      kind: "content",
+      remediation: "Set chromeBindings.mdxExtras.CodeGroup to the local CodeGroup."
+    }
   },
   details: {
     packageSubpath: "@takazudo/zudo-doc/details",
-    localDir: "src/components/zudo-doc/details"
+    localDir: "src/components/zudo-doc/details",
+    classification: {
+      kind: "content",
+      remediation: "Set chromeBindings.mdxExtras.Details to the local Details component."
+    }
   },
   "sidebar-tree-island": {
     packageSubpath: "@takazudo/zudo-doc/sidebar-tree-island",
-    localDir: "src/components/zudo-doc/sidebar-tree-island"
+    localDir: "src/components/zudo-doc/sidebar-tree-island",
+    classification: {
+      kind: "nested",
+      remediation: "Replace the chromeBindings.Sidebar primary component with a project-owned sidebar composition that imports the local SidebarTree island."
+    }
   },
   "sidebar-toggle-island": {
     packageSubpath: "@takazudo/zudo-doc/sidebar-toggle-island",
-    localDir: "src/components/zudo-doc/sidebar-toggle-island"
+    localDir: "src/components/zudo-doc/sidebar-toggle-island",
+    classification: {
+      kind: "nested",
+      remediation: "Replace the chromeBindings.Header primary component with a project-owned header composition that imports the local SidebarToggle island."
+    }
   },
   "desktop-sidebar-toggle-island": {
     packageSubpath: "@takazudo/zudo-doc/desktop-sidebar-toggle-island",
-    localDir: "src/components/zudo-doc/desktop-sidebar-toggle-island"
+    localDir: "src/components/zudo-doc/desktop-sidebar-toggle-island",
+    classification: {
+      kind: "nested",
+      remediation: "Disable settings.sidebarToggle, then replace the chromeBindings.Sidebar primary component with a project-owned composition that imports the local DesktopSidebarToggle island."
+    }
   },
   "image-enlarge": {
     packageSubpath: "@takazudo/zudo-doc/image-enlarge",
-    localDir: "src/components/zudo-doc/image-enlarge"
+    localDir: "src/components/zudo-doc/image-enlarge",
+    classification: {
+      kind: "nested",
+      remediation: "Replace chromeBindings.BodyEndIslands with a project-owned composition that imports the local ImageEnlarge island."
+    }
   },
   "doc-history": {
     packageSubpath: "@takazudo/zudo-doc/doc-history",
-    localDir: "src/components/zudo-doc/doc-history"
+    localDir: "src/components/zudo-doc/doc-history",
+    classification: {
+      kind: "nested",
+      remediation: "Set chromeBindings.DocHistory to the local DocHistory component."
+    }
   },
   "site-tree-nav-island": {
     packageSubpath: "@takazudo/zudo-doc/site-tree-nav-island",
-    localDir: "src/components/zudo-doc/site-tree-nav-island"
+    localDir: "src/components/zudo-doc/site-tree-nav-island",
+    classification: {
+      kind: "nested",
+      remediation: "Set chromeBindings.mdxExtras.SiteTreeNav to a project-owned wrapper that imports the local SiteTreeNav island. A project-owned home route must also use that wrapper if its home grid should change."
+    }
   }
 };
+const CUSTOMIZING_GUIDE_URL = "https://zudo-doc.takazudomodular.com/docs/reference/customizing/";
+const MDX_EXTRAS_GUIDE_URL = "https://zudo-doc.takazudomodular.com/docs/guides/custom-components/#global-registration-mdxextras";
+function assertNeverClassification(value) {
+  throw new Error(`Unknown ejectable classification: ${JSON.stringify(value)}`);
+}
+function chromeRemediation(classification) {
+  switch (classification.kind) {
+    case "primary":
+      return `Export the local component as chromeBindings.${classification.slot} (the ${classification.slot} primary replacement slot) from your chromeBindingsModule.`;
+    case "nested":
+      return classification.remediation;
+    case "content":
+      throw new Error("Content-layer ejectables do not use chrome remediation.");
+    default:
+      return assertNeverClassification(classification);
+  }
+}
+function printNoCallSiteGuidance(entry, component) {
+  const classification = entry.classification;
+  if (classification.kind === "content") {
+    console.log(
+      pc.dim(
+        `  No host call sites found for ${entry.packageSubpath}.
+  This is expected for a content-layer copy. ${classification.remediation}
+  Guide: ${MDX_EXTRAS_GUIDE_URL}`
+      )
+    );
+    return false;
+  }
+  console.warn(
+    pc.bold(pc.red(`
+WARNING: the ejected ${component} copy is not wired into your site.`)) + `
+This component is rendered by package chrome. The source was copied to ${entry.localDir}, but no host import referenced ${entry.packageSubpath}.
+` + pc.bold("Editing the copy will not change your site until you bind it.") + `
+Remediation: ${chromeRemediation(classification)}
+Customization guide: ${CUSTOMIZING_GUIDE_URL}
+`
+  );
+  return true;
+}
 async function rewireImports(dir) {
   const re = /(from\s+)(["'])\.\.\/([\w-]+)\/[^"']+\2/g;
   const entries = await fs.readdir(dir, { withFileTypes: true });
@@ -93,6 +187,7 @@ async function rewireImports(dir) {
 }
 async function rewireHostCallSites(projectRoot, component, localDir) {
   const packageSubpath = EJECTABLE[component].packageSubpath;
+  const destinationDir = path.resolve(projectRoot, localDir);
   const escapedSubpath = packageSubpath.replace(/[/\\^$*+?.()|[\]{}]/g, "\\$&");
   const re = new RegExp(`(from\\s+)(["'])${escapedSubpath}\\2`, "g");
   const searchDirs = [
@@ -106,6 +201,10 @@ async function rewireHostCallSites(projectRoot, component, localDir) {
       const entries = await fs.readdir(dir, { withFileTypes: true });
       for (const entry of entries) {
         const abs = path.join(dir, entry.name);
+        const resolvedAbs = path.resolve(abs);
+        if (resolvedAbs === destinationDir || resolvedAbs.startsWith(`${destinationDir}${path.sep}`)) {
+          continue;
+        }
         if (entry.isDirectory()) {
           await rewriteDir(abs, path.join(relFromProject, entry.name));
           continue;
@@ -114,8 +213,7 @@ async function rewireHostCallSites(projectRoot, component, localDir) {
         const original = await fs.readFile(abs, "utf8");
         if (!original.includes(packageSubpath)) continue;
         const fileDir = path.join(projectRoot, relFromProject);
-        const destAbs = path.join(projectRoot, localDir);
-        let rel = path.relative(fileDir, destAbs).split(path.sep).join("/");
+        let rel = path.relative(fileDir, destinationDir).split(path.sep).join("/");
         if (!rel.startsWith(".")) rel = `./${rel}`;
         const rewritten = original.replace(re, (_, from, quote) => {
           return `${from}${quote}${rel}${quote}`;
@@ -219,27 +317,23 @@ Bump @takazudo/zudo-doc to a version that includes the eject/ tree and retry.`
   await rewireImports(destAbs);
   console.log(pc.dim(`  Rewired cross-component imports in ${localDir}`));
   const rewroteCount = await rewireHostCallSites(cwd, component, localDir);
+  let unwiredChrome = false;
   if (rewroteCount > 0) {
     console.log(
       pc.dim(`  Rewrote ${rewroteCount} host file(s) to import from ${localDir}`)
     );
   } else {
-    console.log(
-      pc.dim(
-        `  No host call sites found for ${entry.packageSubpath}.
-  Update your imports manually: change the \`"${entry.packageSubpath}"\`
-  specifier to a local one, e.g. \`"@/${localDir}/index.js"\` or a relative path.`
-      )
-    );
+    unwiredChrome = printNoCallSiteGuidance(entry, component);
   }
   provenance.packageVersion = installedVersion;
   provenance.ejected[component] = localDir;
   await fs.writeJson(provenancePath, provenance, { spaces: 2 });
   console.log(pc.green(`Updated .zudo-doc.json`));
+  const status = unwiredChrome ? `${pc.yellow("\u26A0")} Copied ${component}, but it is not wired into the rendered site` : `${pc.green("\u2713")} Ejected ${component}`;
   console.log(
     pc.bold(
       `
-${pc.green("\u2713")} Ejected ${component} from @takazudo/zudo-doc@${installedVersion}
+${status} from @takazudo/zudo-doc@${installedVersion}
   Source:      node_modules/@takazudo/zudo-doc/eject/${component}/
   Destination: ${localDir}/
   Provenance:  .zudo-doc.json

package/dist/extract-headings/index.d.ts CHANGED Viewed

@@ -1,5 +1,3 @@
-/** Heading-ID (anchor) strategy. Mirrors `settings.headingIdStrategy`. */
-export type HeadingIdStrategy = "flat" | "hierarchical";
 /**
  * Slugify one heading's text — a byte-faithful TS port of zfb's Rust `slugify`
  * (`crates/zfb-content/src/plugins/heading_links.rs`). Using the exact upstream
@@ -20,9 +18,9 @@ export interface HeadingItem {
 /**
  * Extract TOC headings from a raw MDX/markdown body.
  *
- * Uses the same slugging algorithm as zfb's `HeadingLinks` plugin (selected by
- * `opts.strategy`) so the `href="#slug"` values in the TOC match the rendered
- * heading element IDs. Allocates over ALL matched h2–h6 (keeping the dedup
+ * Uses the same hierarchical slugging algorithm as zfb's `HeadingLinks` plugin
+ * so the `href="#slug"` values in the TOC match the rendered heading element
+ * IDs. Allocates over ALL matched h2–h6 (keeping the dedup
  * counter and hierarchical ancestor stack in sync with the renderer) but only
  * pushes depth 2–4 items into the result (configurable via opts). h1 is not
  * matched — the renderer does not assign ids to h1.
@@ -32,12 +30,11 @@ export interface HeadingItem {
  * This keeps the package import-graph free of project singletons.
  *
  * @param body - Raw markdown body string (frontmatter already stripped).
- * @param opts - Settings for heading depth window and ID strategy. Production
- *   call sites should pass values from the project's `settings` object.
+ * @param opts - Settings for the heading depth window. Production call sites
+ *   should pass values from the project's `settings` object.
  * @returns Array of `{ depth, slug, text }` items in document order.
  */
 export declare function extractHeadings(body: string, opts?: {
     tocMinDepth?: number;
     tocMaxDepth?: number;
-    strategy?: HeadingIdStrategy;
 }): HeadingItem[];

package/dist/extract-headings/index.js CHANGED Viewed

@@ -21,19 +21,12 @@ function slugify(input) {
   return out;
 }
 class SlugAllocator {
-  strategy;
   /** Dedup counter, keyed by the (possibly ancestor-prefixed) slug path. */
   seen = /* @__PURE__ */ new Map();
-  /** Hierarchical ancestor stack of `{ depth, final id }` (unused when flat). */
+  /** Hierarchical ancestor stack of `{ depth, final id }`. */
   stack = [];
-  constructor(strategy) {
-    this.strategy = strategy;
-  }
   allocate(depth, text) {
     const base = slugify(text);
-    if (this.strategy === "flat") {
-      return this.nextSlug(base);
-    }
     if (base === "") return "";
     for (let top = this.stack.at(-1); top !== void 0 && top.depth >= depth; top = this.stack.at(-1)) {
       this.stack.pop();
@@ -74,7 +67,7 @@ function extractHeadings(body, opts) {
     opts?.tocMinDepth ?? 2,
     opts?.tocMaxDepth ?? 4
   );
-  const allocator = new SlugAllocator(opts?.strategy ?? "flat");
+  const allocator = new SlugAllocator();
   const headings = [];
   let codeFenceOpener = null;
   for (const line of body.split("\n")) {

package/dist/factory-context/index.d.ts CHANGED Viewed

@@ -1,5 +1,6 @@
 import type { Settings, TagVocabularyEntry } from "../settings.js";
 import type { ColorScheme } from "../color-scheme-utils.js";
+import type { ThemePackRegistry } from "../theme-packs-registry/index.js";
 import type { UrlHelpers } from "../url-helpers/index.js";
 import type { NavSourceDocsAPI } from "../nav-source-docs/index.js";
 import type { DocRouteEntriesAPI } from "../doc-route-entries/index.js";
@@ -8,6 +9,7 @@ import type { ResolvedTag } from "../tag-helpers/index.js";
 import type { DocNavNode, DocPageEntry } from "../doc-page-props/index.js";
 import type { HeadingItem } from "../extract-headings/index.js";
 import type { CategoryMeta } from "../sidebar-tree/index.js";
+import type { HeaderRightComponentRegistry } from "../header/types.js";
 /**
  * The i18n surface a factory may read. Parameterizes what `base.ts` used to read
  * off the project's `@/config/i18n` singleton directly, so URL/locale logic moves
@@ -103,6 +105,21 @@ export interface RouteContextPayload<S = Settings> {
     /** Host color-scheme palette map; `null` when the host passed none (chrome
      *  then falls back to a neutral default scheme). */
     colorSchemes: Record<string, ColorScheme> | null;
+    /**
+     * Resolved, enabled, ordered theme-pack registry (ADR
+     * `docs/adr/theme-packs.md`, Decision 2 "Registry threading to
+     * SSR/islands") — settings ∩ the bundled `theme-packs/` directories, in
+     * switcher order. `null` (or omitted) renders the whole feature inert (same
+     * accepted coupling class as {@link colorSchemes} for a
+     * `packageOwnedRoutes: false` host that builds its own payload without
+     * threading one).
+     *
+     * OPTIONAL on purpose: this field was added after the payload shape
+     * shipped, so an existing `packageOwnedRoutes: false` host that constructs
+     * its own payload predates it. `createRouteContext` normalizes an omitted
+     * value to `null` (→ inert) so upgrading such a host does not throw at SSR.
+     */
+    themePackRegistry?: ThemePackRegistry | null;
 }
 /** Aggregated `tag → docs` index entry built by `collectTags`. */
 export interface TagInfo {
@@ -133,6 +150,9 @@ export interface RouteContext<S = Settings> extends UrlHelpers, NavSourceDocsAPI
     settings: S;
     /** Host color-scheme palette map (or `null`); threaded to chrome head CSS. */
     colorSchemes: Record<string, ColorScheme> | null;
+    /** Resolved, enabled, ordered theme-pack registry (or `null`) — see
+     *  {@link RouteContextPayload.themePackRegistry}. */
+    themePackRegistry: ThemePackRegistry | null;
     /** The reconstructed i18n surface. */
     i18n: FactoryI18n;
     /** Default locale code (un-prefixed `/docs/...`). */
@@ -162,14 +182,14 @@ export interface RouteContext<S = Settings> extends UrlHelpers, NavSourceDocsAPI
     resolveTagBound(raw: string): ResolvedTag;
     /** Aggregate a `tag → docs` index from a doc collection. */
     collectTags(entries: ReadonlyArray<{
-        id: string;
+        slug: string;
         data: {
             slug?: string;
             title?: string;
             description?: string;
             tags?: string[];
         };
-    }>, slugFn: (id: string, data: {
+    }>, slugFn: (entrySlug: string, data: {
         slug?: string;
     }) => string): Map<string, TagInfo>;
     /** Build a recursive nav tree from a flat doc collection. */
@@ -188,8 +208,8 @@ export interface RouteContext<S = Settings> extends UrlHelpers, NavSourceDocsAPI
     isNavVisible(doc: DocPageEntry): boolean;
     /** The content-bridge handle: identity-stable, draft-filtered docs loader. */
     stableDocs(collectionName: string): DocPageEntry[];
-    /** Canonical route slug for a doc id. */
-    toRouteSlug(id: string): string;
+    /** Canonical route slug for a zfb content slug. */
+    toRouteSlug(entrySlug: string): string;
     /** Split a route slug into path params. */
     toSlugParams(routeSlug: string): string[];
 }
@@ -202,8 +222,26 @@ export interface RouteContext<S = Settings> extends UrlHelpers, NavSourceDocsAPI
  * (HOSTCOLLAPSE wave) later passes the real bindings.
  */
 export interface ChromeHostBindings {
+    /** Primary header chrome. Default: the package HeaderWithDefaults component. */
+    Header?: FactoryComponent;
+    /** Primary footer chrome. Default: the package FooterWithDefaults component. */
+    Footer?: FactoryComponent;
+    /** Primary doc sidebar chrome. Default: the package SidebarWithDefaults component. */
+    Sidebar?: FactoryComponent;
+    /** Primary desktop table of contents. Default: the package Toc component. */
+    Toc?: FactoryComponent;
+    /** Primary breadcrumb trail. Default: the package Breadcrumb component. */
+    Breadcrumb?: FactoryComponent;
+    /** Primary previous/next document pager. Default: the package DocPager component. */
+    DocPager?: FactoryComponent;
     /** Header search widget. Default: the package SearchWidget bound to the site base. */
     SearchWidget?: FactoryComponent;
+    /**
+     * Project-owned header-right renderers keyed by the serializable component
+     * name in `settings.headerRightItems`. Built-in names are reserved and may
+     * not be shadowed. Default: `{}`.
+     */
+    headerRightComponents?: HeaderRightComponentRegistry;
     /** Per-page git-history meta manifest. Default: `{}` (no Created/Updated block). */
     docHistoryMeta?: Record<string, unknown>;
     /** Sidebar section config. Default: `{}` (auto-generated tree only). */
@@ -221,6 +259,20 @@ export interface ChromeHostBindings {
     BodyEndIslands?: FactoryComponent;
     /** DocHistory island. Default: a no-op stub rendering an empty fragment. */
     DocHistory?: FactoryComponent;
+    /**
+     * Design-token panel bootstrap island (#2658). Default: the PACKAGE-DEFAULT
+     * `DesignTokenPanelBootstrap` from
+     * `@takazudo/zudo-doc/design-token-panel-bootstrap`, statically imported by
+     * `chrome/derive.tsx` (`deriveBodyEndIslands`) so EVERY `createChrome`
+     * consumer — the injected `routes/_chrome.tsx` path and the locked-manifest
+     * self-contained doc stub alike — gets the settings-gated panel island with
+     * no explicit wiring (#2659 gate-2 fix; scanner reachability holds through
+     * the static route → chrome → derive → bootstrap chain, the #2480
+     * contract). Supply this slot only to REPLACE the island with a host's own
+     * bootstrap component. Mounting is still gated on
+     * `settings.designTokenPanel` inside `createBodyEndIslands` either way.
+     */
+    DesignTokenPanelBootstrap?: FactoryComponent;
     /** MDX content-component overrides (Details / HtmlPreview / Island /
      *  PresetGenerator). Default: package SSR impls + a `PresetGenerator` stub. */
     mdxExtras?: Record<string, FactoryComponent>;