@takazudo/zudo-doc 3.3.0 → 4.1.0

package/dist/doc-page-props/index.d.ts

@@ -1,6 +1,7 @@
 export type { HeadingItem } from "../extract-headings/index.js";
 import type { HeadingItem } from "../extract-headings/index.js";
 import type { BreadcrumbItem } from "../breadcrumb/types.js";
+import type { CollectionEntry } from "@takazudo/zfb/content";
 /**
  * Nav tree node shape as consumed by doc-route pages.
  *
@@ -35,37 +36,20 @@ export interface DocPageFrontmatter {
     draft?: boolean;
     unlisted?: boolean;
     standalone?: boolean;
+    sidebar_position?: number;
+    sidebar_label?: string;
     category_no_page?: boolean;
+    category_sort_order?: "asc" | "desc";
     pagination_prev?: string | null;
     pagination_next?: string | null;
     tags?: string[];
     [key: string]: unknown;
 }
 /**
- * A zfb content collection entry augmented with the `id`/`collection` fields
- * the host's `@/utils/docs` helpers expect, plus the typed `data` and
- * renderer surface.
- *
- * Structural counterpart of the host's `DocPageEntry` (from
- * `pages/lib/doc-page-props.ts`). The host stub re-exports this type under
- * the original name.
+ * The native zfb collection entry with docs frontmatter. Route consumers
+ * derive canonical route slugs from `entry.data.slug ?? toRouteSlug(entry.slug)`.
  */
-export interface DocPageEntry {
-    /** zfb content engine slug (filename without `.md`/`.mdx`). */
-    slug: string;
-    /** Bridged from `slug` for host `@/utils/docs` compat. */
-    id: string;
-    /** Collection name, e.g. "docs", "docs-ja", "docs-v-1.0". */
-    collection: string;
-    /** Parsed frontmatter. Structural superset of `DocPageFrontmatter`. */
-    data: DocPageFrontmatter;
-    /** Raw MDX body (for heading extraction). */
-    body?: string;
-    /** zfb module specifier (for Content bridge). */
-    module_specifier: string;
-    /** zfb content renderer — callable Preact component. */
-    Content: unknown;
-}
+export type DocPageEntry = CollectionEntry<DocPageFrontmatter>;
 export interface AutoIndexNode extends DocNavNode {
     children: DocNavNode[];
 }

package/dist/doc-page-renderer/index.d.ts

@@ -121,6 +121,7 @@ export interface DocPageRendererDeps {
         slug: string;
         locale: string;
         entrySlug?: string;
+        sourceFileExt?: ".mdx" | ".md";
         contentDir?: string;
         isFallback?: boolean;
     }) => VNode | null;

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

@@ -102,6 +102,7 @@ function createRenderDocPage(ctx) {
               slug,
               locale,
               entrySlug: props.entry.slug,
+              sourceFileExt: props.entry.module_specifier.endsWith(".mdx") ? ".mdx" : props.entry.module_specifier.endsWith(".md") ? ".md" : void 0,
               contentDir: opts.docHistoryContentDir,
               isFallback
             }

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

@@ -1,29 +1,32 @@
 import { Fragment, jsx, jsxs } from "preact/jsx-runtime";
 import { Island } from "@takazudo/zfb";
 import { DocLayoutWithDefaults } from "../doclayout/index.js";
-import { Toc, MobileToc, getTocTitle } from "../toc/index.js";
-import { Breadcrumb } from "../breadcrumb/index.js";
+import { MobileToc, getTocTitle } from "../toc/index.js";
 import { NavCardGrid } from "../nav-indexing/index.js";
 import {
   createSidebarPrepaint,
   createSidebarVisibilityPrepaint
 } from "../sidebar-prepaint/index.js";
 import { createHeadWithDefaults } from "../head-with-defaults/index.js";
-import { createSidebarWithDefaults } from "../sidebar-with-defaults/index.js";
-import { createHeaderWithDefaults } from "../header-with-defaults/index.js";
-import { createFooterWithDefaults } from "../footer-with-defaults/index.js";
+import { resolveThemePackSsrSlug } from "../theme/theme-pack-provider.js";
 import { createDocBodyEnd } from "../doc-body-end/index.js";
-import { createDocPager } from "../doc-pager/index.js";
 import { deriveComposeMetaTitle } from "../chrome/derive.js";
+import { derivePrimaryChromeSlots } from "../chrome/primary-slots.js";
 import { assertChromeContext } from "../chrome/assert-chrome-context.js";
 function createDocPageShell(ctx) {
   assertChromeContext(ctx, "createDocPageShell");
   const settings = ctx.settings;
   const composeMetaTitle = deriveComposeMetaTitle(ctx);
   const HeadWithDefaults = createHeadWithDefaults(ctx);
-  const SidebarWithDefaults = createSidebarWithDefaults(ctx);
-  const HeaderWithDefaults = createHeaderWithDefaults(ctx);
-  const FooterWithDefaults = createFooterWithDefaults(ctx);
+  const {
+    Header: HeaderWithDefaults,
+    Footer: FooterWithDefaults,
+    Sidebar: SidebarWithDefaults,
+    Toc,
+    Breadcrumb,
+    DocPager
+  } = derivePrimaryChromeSlots(ctx);
+  const customTocIsPresent = ctx.hostBindings.Toc !== void 0;
   const sidebarToggleEnabled = Boolean(
     ctx.settings.sidebarToggle
   );
@@ -34,7 +37,10 @@ function createDocPageShell(ctx) {
     sidebarToggle: sidebarToggleEnabled
   });
   const DocBodyEnd = createDocBodyEnd(ctx);
-  const DocPager = createDocPager(ctx);
+  const dataThemePack = resolveThemePackSsrSlug(
+    ctx.themePackRegistry,
+    ctx.settings
+  );
   function DocPageShell(props) {
     const {
       kind,
@@ -66,7 +72,7 @@ function createDocPageShell(ctx) {
     } = props;
     const tocTitle = getTocTitle(locale);
     const shouldRenderToc = !hideToc && headings.length > 0;
-    const tocOverride = shouldRenderToc ? Island({
+    const tocOverride = shouldRenderToc ? customTocIsPresent ? /* @__PURE__ */ jsx(Toc, { headings, title: tocTitle }) : Island({
       when: "load",
       children: /* @__PURE__ */ jsx(Toc, { headings, title: tocTitle })
     }) : void 0;
@@ -84,6 +90,7 @@ function createDocPageShell(ctx) {
           /* @__PURE__ */ jsx(SidebarVisibilityPrepaint, { hideSidebar })
         ] }),
         lang: locale,
+        dataThemePack,
         noindex: settings.noindex,
         hideSidebar,
         hideToc,
@@ -128,7 +135,7 @@ function createDocPageShell(ctx) {
           /* @__PURE__ */ jsxs(Fragment, { children: [
             /* @__PURE__ */ jsx("h1", { class: "text-heading font-bold mb-vsp-xs", children: autoIndexLabel }),
             metainfoSlot,
-            description && /* @__PURE__ */ jsx("p", { class: "mb-vsp-lg text-title text-muted", children: description }),
+            description && /* @__PURE__ */ jsx("p", { class: "mb-vsp-lg text-title text-muted", "data-doc-description": true, children: description }),
             /* @__PURE__ */ jsx(NavCardGrid, { children: autoIndexChildren ?? [] })
           ] })
         ) : (

package/dist/doc-pager/index.js

@@ -5,7 +5,7 @@ function createDocPager(ctx) {
   assertChromeContext(ctx, "createDocPager");
   const t = ctx.t;
   function DocPager({ prev, next, locale }) {
-    return /* @__PURE__ */ jsxs("nav", { class: "mt-vsp-2xl grid grid-cols-2 gap-hsp-xl", children: [
+    return /* @__PURE__ */ jsxs("nav", { class: "mt-vsp-2xl grid grid-cols-2 gap-hsp-xl", "data-doc-pager": true, children: [
       prev ? /* @__PURE__ */ jsxs(
         "a",
         {

package/dist/doc-route-entries/index.d.ts

@@ -63,7 +63,7 @@ export interface DocRouteEntriesContext {
     /** Filter top-level nav nodes by a categoryMatch value. */
     getNavSubtree: (tree: DocNavNode[], categoryMatch?: string) => DocNavNode[];
     /** Convert a content entry slug to a canonical route slug. */
-    toRouteSlug: (id: string) => string;
+    toRouteSlug: (entrySlug: string) => string;
     /** Convert a canonical route slug to an optional-catchall params array. */
     toSlugParams: (slug: string) => string[];
     /** Extract headings from a raw MDX body (bound to settings depth/strategy). */
@@ -91,7 +91,7 @@ export interface DocRouteEntriesAPI {
  * import { createDocRouteEntries } from "@takazudo/zudo-doc/doc-route-entries";
  * import { buildNavTree, buildBreadcrumbs, collectAutoIndexNodes } from "@/utils/docs";
  * import { getNavSectionForSlug, getNavSubtree } from "@/utils/nav-scope";
- * import { toRouteSlug, toSlugParams } from "@/utils/slug";
+ * import { toRouteSlug, toSlugParams } from "@takazudo/zudo-doc/slug";
  * import { extractHeadings } from "./_extract-headings";
  *
  * export const { buildDocRouteEntries } = createDocRouteEntries(routeContext);

package/dist/doclayout/doc-layout-with-defaults.js

@@ -120,10 +120,10 @@ function DocLayoutWithDefaults(props) {
       footer: footerOverride ?? /* @__PURE__ */ jsx(Footer, {}),
       bodyEndComponents,
       bodyEndScripts: bodyEndScripts ?? // Default body-end scripts:
-      //   - CodeBlockEnhancer wraps every <pre class="syntect-*"> with
-      //     copy + word-wrap controls and emits an SR-announce live
-      //     region for clipboard feedback. Idempotent on pages with no
-      //     fenced code.
+      //   - CodeBlockEnhancer wraps every highlighted <pre> (`.hi-root`)
+      //     with copy + word-wrap controls and emits an SR-announce live
+      //     region for clipboard feedback.
+      //     Idempotent on pages with no fenced code.
       //   - TabsInit activates the correct tab panel and wires click
       //     handlers for <Tabs> components.
       //   - MermaidInit lazily imports the mermaid library from

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

@@ -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

@@ -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.js

@@ -3,11 +3,7 @@ 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 = /* @__PURE__ */ new Set();
-  for (const entry of vocabulary) {
-    allowed.add(entry.id);
-    for (const alias of entry.aliases ?? []) allowed.add(alias);
-  }
+  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;

package/dist/eject/index.d.ts

@@ -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

@@ -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

@@ -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

@@ -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")) {