create-zudo-doc 0.2.22 → 1.0.0

package/templates/base/pages/_mdx-components.ts

@@ -1,117 +1,52 @@
-// Shared MDX-component bag used by every doc-route page that renders
-// `<entry.Content components={...} />`.
+// Project MDX-components assembly — thin wrapper over the package factory.
 //
-// ## Why a shared helper
+// The bulk of the components bag (htmlOverrides, admonitions, CodeGroup,
+// Tabs/TabItem, MathBlock, the img base-rewrite, the enlargeable-`p` override)
+// now ships from `@takazudo/zudo-doc/mdx-components` (package-first migration,
+// epic #2321, S8 #2332). This file keeps ONLY what is genuinely project-bound:
 //
-// Pre-S4e the page-side `components` map only carried `htmlOverrides` plus
-// `HtmlPreview`, because the zfb content bridge wasn't installed and every
-// `<entry.Content>` call took the raw-markdown `<pre data-zfb-content-fallback>`
-// path. Now that the bridge IS installed (zudo-doc#506), the compiled
-// MDXContent functions fire for every entry — and the MDX emitter wraps
-// every named-tag access with:
-//
-//   const CategoryNav2 = _components.CategoryNav ?? components.CategoryNav;
-//   if (!CategoryNav2) throw new Error("MDX requires `CategoryNav` to be passed via the `components` prop");
-//
-// So any tag the MDX corpus uses but the page omits → 500 at render time.
-//
-// ## Strategy
-//
-// This module ships stub bindings for tags not yet ported to `@takazudo/zudo-doc`
-// (render nothing), and real Preact bindings for tags whose ports are complete.
-// As real components land, they replace their stub here and propagate to every page automatically.
-//
-// `htmlOverrides` (basic typography — h2/h3/h4/p/a/ul/ol/blockquote/strong/table)
-// and `HtmlPreview: HtmlPreviewWrapper` (Island wrapper) stay in their
-// non-stub form because their Preact bindings already exist.
-//
-// ## Locale-aware bindings (createMdxComponents factory)
-//
-// CategoryNav, CategoryTreeNav, SiteTreeNav, and SiteTreeNavDemo resolve nav
-// tree data at render time. Since the same MDX content is rendered for both
-// default-locale and non-default-locale pages, these components need to know
-// which locale to use when building the nav tree.
-//
-// The `createMdxComponents(lang)` factory returns a components map with
-// locale-bound wrappers for these nav components. Page modules should call it
-// with the active locale instead of using the static `mdxComponents` export.
-// The static export still exists for backward compatibility (using defaultLocale).
+//   - the 4 locale-bound nav wrappers (CategoryNav / CategoryTreeNav /
+//     SiteTreeNav / SiteTreeNavDemo) — they depend on the project's content
+//     collections + nav-tree utilities, so they cannot live in the package.
+//     They are passed into the factory as `navData`; the factory injects the
+//     active `locale` so `/ja` resolves the JA collection (the load-bearing
+//     locale thread — a static global mdx-components slot would render the EN
+//     tree on every `/ja` page, which is why this stays a per-call factory).
+//   - project `extras` spread last: HtmlPreview (with the host's global
+//     config), Details, the Island SSR pass-through, the PresetGenerator SSR
+//     shell, and the pure-showcase stubs (Avatar/Button/Card/MyComponent/
+//     PageLayout) that appear only as illustrative MDX prose.
 
 import type { ComponentChildren } from "preact";
-// @slot:mdx-components:enlarge-imports
-import { htmlOverrides } from "@takazudo/zudo-doc/content";
+import { createMdxComponents as createMdxComponentsBase } from "@takazudo/zudo-doc/mdx-components";
 import { HtmlPreviewWrapper, type HtmlPreviewWrapperProps } from "@takazudo/zudo-doc/html-preview-wrapper";
-import { Tabs } from "@takazudo/zudo-doc/code-syntax";
-import { TabItem } from "@takazudo/zudo-doc/tab-item";
 import { defaultLocale, type Locale } from "@/config/i18n";
 import { settings } from "@/config/settings";
-import { withBase } from "@/utils/base";
 import { CategoryNavWrapper } from "./lib/_category-nav";
 import { CategoryTreeNavWrapper } from "./lib/_category-tree-nav";
 import { SiteTreeNavWrapper } from "./lib/_site-tree-nav";
 import { DetailsWrapper } from "./lib/_details";
 import { PresetGeneratorFallback } from "./lib/_preset-generator";
-import { MathBlock } from "./lib/_math-block";
-import { CodeGroup } from "@/components/content/code-group";
-import { makeAdmonition } from "@/components/content/content-admonition";
 
-/**
- * MDX `<img>` override — rewrites root-relative src attributes to include the
- * configured site base path (settings.base). Without this, an MDX image like
- * `![alt](/img/foo.webp)` emits `src="/img/foo.webp"` which 404s when the
- * site is deployed under a sub-path prefix (e.g. /my-docs/).
- *
- * Only root-relative paths (starting with "/") are rewritten; external URLs,
- * protocol-relative URLs ("//…"), and data URIs pass through unchanged. The
- * withBase() call is generic — it reads settings.base at build time and applies
- * whatever prefix is configured.
- *
- * Note: `srcset` attributes are NOT rewritten here because the current MDX
- * corpus does not use srcset (standard markdown `![alt](src)` syntax produces
- * only `src`). If srcset with root-relative URLs is ever introduced, extend
- * this override to rewrite each srcset candidate URL as well.
- */
-function ContentImg(props: Record<string, unknown>) {
-  const src = props.src;
-  const rewrittenSrc =
-    typeof src === "string" && src.startsWith("/") && !src.startsWith("//")
-      ? withBase(src)
-      : src;
-  // Strip the "no-enlarge" sentinel from the rendered DOM — it is read by the
-  // p-override before ContentImg is called (the VNode is still unlaunched at
-  // that point), so we must delete it here to avoid leaking the sentinel into
-  // the img title attribute.
-  const { title, ...restProps } = props;
-  const finalTitle = title === "no-enlarge" ? undefined : title;
-  const mergedProps: Record<string, unknown> = { ...restProps, src: rewrittenSrc };
-  if (finalTitle !== undefined) {
-    mergedProps.title = finalTitle;
-  }
-  return { type: "img", props: mergedProps, key: null, constructor: undefined };
-}
+const HtmlPreviewWithGlobalConfig = (props: HtmlPreviewWrapperProps) =>
+  HtmlPreviewWrapper({ globalConfig: settings.htmlPreview ?? null, ...props });
 
 /**
- * MDX-tag stub: renders nothing. Returning `null` keeps the rendered
- * tree intact (Preact's null-vnode path) without leaking placeholder
- * markup into the SSR output.
+ * MDX-tag stub: renders nothing. Returning `null` keeps the rendered tree
+ * intact (Preact's null-vnode path) without leaking placeholder markup into
+ * the SSR output.
  */
 const MdxStub = (_props: unknown) => null;
 
 /**
  * SSR-pass-through wrapper for `<Island when="load|idle|visible">`.
  *
- * In the zfb build the zfb `<Island>` component is unavailable, so the
- * MDX corpus tags resolve to this binding instead. Rendering the
- * children directly ensures that any server-renderable content nested
- * inside `<Island>` (headings, paragraphs, etc.) appears in the SSR
- * HTML. Client-only inner components that are themselves wrapped in an
- * SSR-skip placeholder will emit their own placeholder markup; this
- * wrapper does not suppress them.
- *
- * The `when` prop is intentionally ignored at render time — it is only
- * meaningful to the zfb hydration runtime on the client, which reads
- * the `data-when` attribute on the inner SSR-skip placeholder div (if
- * present) rather than on this wrapper.
+ * In the zfb build the zfb `<Island>` component is unavailable here, so the
+ * MDX corpus tag resolves to this binding instead. Rendering the children
+ * directly ensures server-renderable content nested inside `<Island>`
+ * (headings, paragraphs, etc.) appears in the SSR HTML. The `when` prop is
+ * ignored at render time — it is only meaningful to the zfb hydration runtime
+ * on the client, which reads `data-when` on the inner SSR-skip placeholder.
  */
 function IslandWrapper(props: {
   when?: "load" | "idle" | "visible" | "media";
@@ -120,104 +55,48 @@ function IslandWrapper(props: {
   return props.children ?? null;
 }
 
-// @slot:mdx-components:enlarge-defs
-const HtmlPreviewWithGlobalConfig = (props: HtmlPreviewWrapperProps) =>
-  HtmlPreviewWrapper({ globalConfig: settings.htmlPreview ?? null, ...props });
-
 /**
  * Build a locale-aware MDX components map for the given locale.
  *
- * Nav components (CategoryNav, CategoryTreeNav, SiteTreeNav, SiteTreeNavDemo)
- * resolve nav tree data at render time and need the active locale so they
- * query the right collection. The factory closes over `lang` and returns
- * locale-bound wrapper functions.
- *
- * Page modules should call createMdxComponents(locale) instead of importing
- * the static mdxComponents export.
+ * Delegates the package-resident components to the `@takazudo/zudo-doc`
+ * factory and supplies the project-bound pieces:
+ *   - `navData`: the 4 locale-aware nav wrappers (the factory injects `lang`).
+ *   - `extras`: HtmlPreview (host-configured), Details, Island pass-through,
+ *     PresetGenerator SSR shell, and the showcase stubs.
  *
- * Components map includes:
- * - `htmlOverrides` — element-level overrides for native tags (h2..h4,
- *   p, a, ul/ol, blockquote, strong, table). Defined in
- *   `@takazudo/zudo-doc/content`.
- * - `HtmlPreview` — Island-wrapped preview component.
- * - Real Preact wrappers for CategoryNav, CategoryTreeNav, SiteTreeNav,
- *   SiteTreeNavDemo, and Details.
- * - `Island` — SSR pass-through wrapper so children render server-side.
- * - `PresetGenerator` — SSR fallback shell that renders the 8 h3 sections;
- *   interactive form hydrates client-side via SSR-skip placeholder.
- * - Stub bindings for every other custom tag the MDX corpus references.
- *
- * Keep this list in sync with the corpus when new MDX tags appear.
- * `pnpm exec grep -rohE '<[A-Z][a-zA-Z]+' src/content/` enumerates them.
+ * Page modules should call createMdxComponents(locale) — not the static
+ * mdxComponents export — so each render gets the locale-correct map.
  */
 export function createMdxComponents(lang: Locale | string = defaultLocale) {
-  // Locale-bound wrappers — close over `lang` so each wrapper queries
-  // the correct collection without needing a prop.
-  const CategoryNavBound = (props: Record<string, unknown>) =>
-    CategoryNavWrapper({ ...(props as Parameters<typeof CategoryNavWrapper>[0]), lang });
-  const CategoryTreeNavBound = (props: Record<string, unknown>) =>
-    CategoryTreeNavWrapper({ ...(props as Parameters<typeof CategoryTreeNavWrapper>[0]), lang });
-  const SiteTreeNavBound = (props: Record<string, unknown>) =>
-    SiteTreeNavWrapper({ ...(props as Parameters<typeof SiteTreeNavWrapper>[0]), lang });
-
-  return {
-    ...htmlOverrides,
-    // img override: rewrites root-relative src to include the site base path.
-    // Required when settings.base is a sub-path (e.g. /my-docs/) so that
-    // MDX images like ![alt](/img/foo.webp) resolve correctly on the deployed
-    // site. withBase() is generic — any configured base value works.
-    img: ContentImg,
-    // @slot:mdx-components:enlarge-p-entry
-    HtmlPreview: HtmlPreviewWithGlobalConfig,
-    // Admonitions — real typed Preact components (src/components/content/
-    // content-admonition.tsx) emitting the `.admonition` / `data-admonition`
-    // structure the design-system CSS targets. The `directives` map in
-    // zfb.config.ts emits these tags from `:::note` directives; `<Note
-    // title="…">` JSX form is also authored directly.
-    Note: makeAdmonition("note"),
-    Tip: makeAdmonition("tip"),
-    Info: makeAdmonition("info"),
-    Warning: makeAdmonition("warning"),
-    Danger: makeAdmonition("danger"),
-    // github-alerts [!IMPORTANT] and [!CAUTION] map to these variants.
-    // Without these bindings, those two alert variants 500 the SSR render.
-    Important: makeAdmonition("important"),
-    Caution: makeAdmonition("caution"),
-    // codeTabs Option A: zfb emits <CodeGroup tabs={[...]}> for :::code-group.
-    // The framework does not ship this component; we implement it here and map
-    // the tabs[] + <pre data-lang> children to the existing Tabs/TabItem UI.
-    CodeGroup: CodeGroup as unknown as (props: Record<string, unknown>) => unknown,
-    // Showcase / nav helpers — real Preact wrappers replacing MdxStub.
-    CategoryNav: CategoryNavBound,
-    CategoryTreeNav: CategoryTreeNavBound,
-    SiteTreeNav: SiteTreeNavBound,
-    SiteTreeNavDemo: SiteTreeNavBound,
-    Details: DetailsWrapper,
-    Tabs,
-    TabItem,
-    // Math rendering — KaTeX via server-side katex.renderToString().
-    // The math-equations.mdx content files write <MathBlock> JSX directly
-    // (instead of $$…$$) because the zfb Rust emitter does not yet support
-    // remark-math math nodes (zudo-front-builder #93).
-    MathBlock,
-    SmartBreak: MdxStub,
-    // Island: pass children through so server-renderable content nested
-    // inside <Island> appears in SSR HTML. See IslandWrapper comment above.
-    Island: IslandWrapper,
-    // PresetGenerator: render the 8 section headings as static SSR HTML for
-    // a11y/SEO section structure and no-JS layout stability. The interactive
-    // form loads client-side via the SSR-skip placeholder inside
-    // PresetGeneratorFallback (see pages/lib/_preset-generator.tsx).
-    PresetGenerator: PresetGeneratorFallback,
-    // Pure showcase placeholders (Avatar/Button/Card/MyComponent/PageLayout
-    // appear only inside MDX prose as illustrative examples — never
-    // implemented as real components).
-    Avatar: MdxStub,
-    Button: MdxStub,
-    Card: MdxStub,
-    MyComponent: MdxStub,
-    PageLayout: MdxStub,
-  };
+  return createMdxComponentsBase({
+    settings,
+    locale: lang,
+    navData: {
+      CategoryNav: CategoryNavWrapper as unknown as (props: Record<string, unknown>) => unknown,
+      CategoryTreeNav: CategoryTreeNavWrapper as unknown as (props: Record<string, unknown>) => unknown,
+      SiteTreeNav: SiteTreeNavWrapper as unknown as (props: Record<string, unknown>) => unknown,
+    },
+    extras: {
+      HtmlPreview: HtmlPreviewWithGlobalConfig,
+      Details: DetailsWrapper,
+      // SmartBreak: corpus tag with no visual rendering — render nothing.
+      SmartBreak: MdxStub,
+      // Island: pass children through so server-renderable content nested
+      // inside <Island> appears in SSR HTML. See IslandWrapper comment above.
+      Island: IslandWrapper,
+      // PresetGenerator: SSR fallback shell that renders the 8 section headings;
+      // the interactive form hydrates client-side via the SSR-skip placeholder
+      // inside PresetGeneratorFallback (see pages/lib/_preset-generator.tsx).
+      PresetGenerator: PresetGeneratorFallback,
+      // Pure showcase placeholders — appear only inside MDX prose as
+      // illustrative examples, never implemented as real components.
+      Avatar: MdxStub,
+      Button: MdxStub,
+      Card: MdxStub,
+      MyComponent: MdxStub,
+      PageLayout: MdxStub,
+    },
+  });
 }
 
 /**

package/templates/base/pages/index.tsx

@@ -27,7 +27,7 @@ import { DocLayoutWithDefaults } from "@takazudo/zudo-doc/doclayout";
 import type { JSX } from "preact";
 import type { VNode } from "preact";
 import { Island } from "@takazudo/zfb";
-import SiteTreeNav from "@/components/site-tree-nav";
+import { SiteTreeNav } from "@takazudo/zudo-doc/site-tree-nav-island";
 import { FooterWithDefaults } from "./lib/_footer-with-defaults";
 import { HeaderWithDefaults } from "./lib/_header-with-defaults";
 import { HeadWithDefaults } from "./lib/_head-with-defaults";

package/templates/base/pages/lib/_extract-headings.ts

@@ -1,239 +1,25 @@
-// pages/lib/_extract-headings.ts — extract TOC headings from a raw MDX body.
+// Thin showcase wrapper around @takazudo/zudo-doc/extract-headings.
+// The package-side extractHeadings takes settings as explicit params (no
+// project singleton import). This wrapper re-reads the project settings and
+// passes them through so call sites in _doc-route-entries.ts continue to
+// call extractHeadings(body) without change.
 //
-// Shared helper called by all four catch-all `paths()` functions so each page
-// passes real heading data to `DocLayoutWithDefaults` rather than an empty
-// array. The result drops directly into the `headings` prop of `Toc` /
-// `MobileToc` — the shape is byte-aligned with `HeadingItem` in
-// `packages/zudo-doc/src/toc/types.ts`.
-//
-// Algorithm:
-//   1. Walk the body line-by-line looking for ATX-style markdown headings
-//      (`## Text` through `###### Text`, h2–h6).
-//   2. Strip inline markdown markup (links, inline code, bold, italic) from the
-//      heading text to get the plain visible text — matching what the renderer's
-//      `extractText` HAST walker sees after MDX → HTML conversion.
-//   3. Compute a heading ID that matches what zfb's Rust `HeadingLinks` plugin
-//      emits at render time, using the strategy in `settings.headingIdStrategy`
-//      (single source of truth, also read by `zfb.config.ts`):
-//        - `"flat"`: one dedup counter shared across ALL h2–h6 (even those not
-//          emitted into the TOC), so TOC anchor hrefs match the rendered IDs.
-//        - `"hierarchical"`: ancestor-prefixed IDs (`## Foo` / `### Moo` /
-//          `#### Mew` → `foo`, `foo-moo`, `foo-moo-mew`), deduped on the full
-//          path — see `SlugAllocator` below, a faithful mirror of zfb's Rust
-//          allocator (upstream zfb#871).
-//      Either way the allocator runs over ALL matched h2–h6 so its per-document
-//      state (dedup counter + ancestor stack) stays in lockstep with the
-//      renderer. h1 is NOT slugged — the renderer never assigns an id to h1.
-//   4. Return only depth 2–4 headings by default (h1 is the page title; h5–h6
-//      are too granular). The window is configurable via `tocMinDepth` /
-//      `tocMaxDepth` in settings (restriction-only: min 2, max 4).
-//
-// Caveats:
-//   - This is a regex walk over raw text, not an AST parse. MDX JSX expressions
-//     that contain `##` on their own line may be matched. In practice this is
-//     rare.
-//   - Lines inside code fences (``` … ``` or ~~~ … ~~~) are skipped to avoid
-//     treating literal `## code` examples as real headings. Fence detection
-//     uses `line.trimStart()` to handle indented fences correctly.
-//   - Reference-style links (`[text][id]`) and image links (`![alt](url)`)
-//     are not stripped — uncommon in headings, treated as plain text.
-//   - The renderer slugs all h2–h6 regardless of `tocMinDepth`/`tocMaxDepth`, so
-//     this extractor must also allocate over every matched heading (including
-//     those outside the emit window) to keep the shared dedup counter / ancestor
-//     stack in sync.
-//   - Slug parity: we port zfb's exact Rust `slugify` (see `slugify` below)
-//     instead of using npm `github-slugger`, because the two diverge on
-//     punctuation (`.` → `-` vs removed, `/`/`—` collapsing, etc.) and that
-//     divergence would desync the TOC anchor from the rendered heading id.
-//   - Residual risk: text-extraction parity (inline JSX / reference links not
-//     fully stripped) — the slug parity itself is now exact.
+// Moved to the package as part of the package-first migration (#2321, S4 #2327).
 
 import { settings } from "../../src/config/settings";
-
-/** Heading-ID (anchor) strategy. Mirrors `settings.headingIdStrategy`. */
-export type HeadingIdStrategy = "flat" | "hierarchical";
-
-// Punctuation stripped (treated as a separator) by zfb's slugify — the ASCII
-// set from `crates/zfb-content/src/plugins/heading_links.rs::slugify`. Note `-`
-// and `_` are NOT here: they are kept verbatim.
-const SLUGIFY_STRIPPED = new Set(
-  "!\"#$%&'()*+,./:;<=>?@[\\]^`{|}~".split(""),
-);
-
-/**
- * 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
- * algorithm (rather than npm `github-slugger`, which strips punctuation
- * differently) is what keeps the TOC anchor identical to the rendered `id`.
- *
- * Rule: walk code points; whitespace, ASCII control, or a {@link SLUGIFY_STRIPPED}
- * char collapses to a single `-` (runs coalesce); every other char is lowercased
- * and kept (Unicode letters/digits, `-`, `_` survive). A single trailing `-` is
- * dropped; a leading `-` is never emitted.
- */
-export function slugify(input: string): string {
-  let out = "";
-  let lastDash = true; // suppress a leading dash
-  for (const ch of input) {
-    const cp = ch.codePointAt(0) ?? 0;
-    const isControl = cp <= 0x1f || (cp >= 0x7f && cp <= 0x9f);
-    if (isControl || /\s/u.test(ch) || SLUGIFY_STRIPPED.has(ch)) {
-      if (!lastDash) {
-        out += "-";
-        lastDash = true;
-      }
-    } else {
-      out += ch.toLowerCase();
-      lastDash = false;
-    }
-  }
-  if (out.endsWith("-")) out = out.slice(0, -1);
-  return out;
-}
-
-export interface HeadingItem {
-  readonly depth: number;
-  readonly slug: string;
-  readonly text: string;
-}
+export type { HeadingIdStrategy, HeadingItem } from "@takazudo/zudo-doc/extract-headings";
+export { slugify } from "@takazudo/zudo-doc/extract-headings";
+import { extractHeadings as _extractHeadings } from "@takazudo/zudo-doc/extract-headings";
+import type { HeadingItem, HeadingIdStrategy } from "@takazudo/zudo-doc/extract-headings";
 
 /**
- * Per-document heading-ID allocator — a faithful TS mirror of zfb's Rust
- * `SlugAllocator` (`crates/zfb-content/src/plugins/heading_links.rs`). Construct
- * one per document; call `allocate(depth, text)` for every matched h2–h6 in
- * document order (the result is the rendered heading `id`).
- *
- * Both strategies share one `slugify` (the exact zfb port) and one per-document
- * dedup counter:
+ * Extract TOC headings from a raw MDX/markdown body, using the project's
+ * configured `tocMinDepth`, `tocMaxDepth`, and `headingIdStrategy` from
+ * `src/config/settings`.
  *
- * - `"flat"`: `id = nextSlug(slugify(text))` — one counter shared across all
- *   levels (`overview`, `overview-1`, …). Byte-identical to zfb's flat path.
- * - `"hierarchical"`: `base = slugify(text)`; pop the ancestor stack while its
- *   top is at or deeper than `depth`; `candidate = {parent.id}-{base}` (just
- *   `base` at the top of the outline); `id = nextSlug(candidate)` (dedup on the
- *   *full path*); push `(depth, id)`. A deduped parent therefore contributes its
- *   FINAL id to children. Empty-text headings get the empty string and touch no
- *   state (the renderer skips them entirely).
- */
-class SlugAllocator {
-  private readonly strategy: HeadingIdStrategy;
-  /** Dedup counter, keyed by the (possibly ancestor-prefixed) slug path. */
-  private readonly seen = new Map<string, number>();
-  /** Hierarchical ancestor stack of `{ depth, final id }` (unused when flat). */
-  private readonly stack: { depth: number; id: string }[] = [];
-
-  constructor(strategy: HeadingIdStrategy) {
-    this.strategy = strategy;
-  }
-
-  allocate(depth: number, text: string): string {
-    const base = slugify(text);
-    if (this.strategy === "flat") {
-      return this.nextSlug(base);
-    }
-    if (base === "") return "";
-    // Pop ancestors at or below this depth so a sibling/shallower heading
-    // re-roots the chain (h2 → h4 jumps nest under the nearest real ancestor).
-    for (let top = this.stack.at(-1); top !== undefined && top.depth >= depth; top = this.stack.at(-1)) {
-      this.stack.pop();
-    }
-    const parent = this.stack.at(-1);
-    const candidate = parent !== undefined ? `${parent.id}-${base}` : base;
-    const id = this.nextSlug(candidate);
-    this.stack.push({ depth, id });
-    return id;
-  }
-
-  /**
-   * Repeat-numbering on an already-slugified candidate: first occurrence returns
-   * `candidate`, later ones `candidate-1`, `candidate-2`, …. Mirrors zfb's
-   * `next_slug` — including the empty-string short-circuit (an empty base never
-   * advances the counter), so it does NOT re-slugify (the candidate is already a
-   * valid slug path).
-   */
-  private nextSlug(candidate: string): string {
-    if (candidate === "") return "";
-    const count = this.seen.get(candidate) ?? 0;
-    this.seen.set(candidate, count + 1);
-    return count === 0 ? candidate : `${candidate}-${count}`;
-  }
-}
-
-/**
- * Strip inline markdown markup from a heading line to obtain the plain visible
- * text that `rehype-heading-links` sees after MDX → HTML conversion.
- *
- * Strips (in order):
- *   - Inline links: `[text](url)` → `text`
- *   - Inline code spans: `` `code` `` → `code`
- *   - Bold: `**text**` or `__text__` → `text`
- *   - Italic: `*text*` or `_text_` → `text`
- *
- * Underscore emphasis (`__`/`_`) only fires at word boundaries, per CommonMark's
- * intraword rule: `_` inside a word is literal. Without this guard, identifiers
- * like `SKIP_DOC_HISTORY` or `DOCS_SITE_URL` lose their underscores here, and the
- * resulting slug diverges from the rendered heading `id` (the renderer keeps the
- * underscores). Asterisk emphasis (`*`) is left intraword-greedy — `*` does not
- * appear in identifiers and CommonMark does allow intraword `*`.
- */
-function stripInlineMarkdown(raw: string): string {
-  return (
-    raw
-      // Inline links [text](url) — replace with link text only.
-      // Must run before bold/italic to avoid mismatching `*` inside URLs.
-      .replace(/\[([^\]]*)\]\([^)]*\)/g, "$1")
-      // Inline code spans `code` — replace with code text.
-      .replace(/`([^`]+)`/g, "$1")
-      // Bold **text** or __text__ (underscore form only at word boundaries)
-      .replace(/\*\*([^*]+)\*\*/g, "$1")
-      .replace(/(?<![\w])__([^_]+)__(?![\w])/g, "$1")
-      // Italic *text* or _text_ (underscore form only at word boundaries)
-      .replace(/\*([^*]+)\*/g, "$1")
-      .replace(/(?<![\w])_([^_]+)_(?![\w])/g, "$1")
-      .trim()
-  );
-}
-
-/**
- * Resolve and clamp the depth window from raw (possibly invalid) inputs.
- *
- * Enforces `2 <= min <= max <= 4`. If either value is NaN or the chain breaks,
- * falls back to the full default window [2, 4].
- */
-function resolveDepthWindow(
-  rawMin: unknown,
-  rawMax: unknown,
-): { lo: number; hi: number } {
-  const min = Math.trunc(Number(rawMin));
-  const max = Math.trunc(Number(rawMax));
-  if (
-    Number.isFinite(min) &&
-    Number.isFinite(max) &&
-    min >= 2 &&
-    min <= max &&
-    max <= 4
-  ) {
-    return { lo: min, hi: max };
-  }
-  return { lo: 2, hi: 4 };
-}
-
-/**
- * Extract TOC headings from a raw MDX/markdown body.
- *
- * Uses the same slugging algorithm as zfb's `HeadingLinks` plugin (selected by
- * `settings.headingIdStrategy`, or the `opts.strategy` override) 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 settings). h1 is not matched — the renderer
- * does not assign ids to h1.
- *
- * @param body - Raw markdown body string (frontmatter already stripped).
- * @param opts - Optional overrides for the depth window and heading-ID
- *   strategy (used by tests only; production call sites pass no arguments and
- *   read from settings).
- * @returns Array of `{ depth, slug, text }` items in document order.
+ * Accepts the same optional `opts` overrides as the underlying package
+ * function (for tests that want to override the depth window or strategy
+ * without touching the global settings).
  */
 export function extractHeadings(
   body: string,
@@ -243,69 +29,9 @@ export function extractHeadings(
     strategy?: HeadingIdStrategy;
   },
 ): HeadingItem[] {
-  const { lo, hi } = resolveDepthWindow(
-    opts?.tocMinDepth ?? settings.tocMinDepth,
-    opts?.tocMaxDepth ?? settings.tocMaxDepth,
-  );
-
-  const allocator = new SlugAllocator(opts?.strategy ?? settings.headingIdStrategy);
-  const headings: HeadingItem[] = [];
-
-  // Track the opening fence character and length so we correctly match the
-  // closing fence. Markdown allows backtick and tilde fences (``` or ~~~),
-  // and longer fences to nest shorter same-character ones.
-  let codeFenceOpener: string | null = null;
-  for (const line of body.split("\n")) {
-    // Detect code fence open/close. A fence is 3+ backticks OR 3+ tildes,
-    // optionally followed by a language specifier. The closing fence must use
-    // the same character and match or exceed the opener's length.
-    // Use trimStart() so indented fences (e.g. inside lists) are also detected.
-    const trimmed = line.trimStart();
-    const fenceMatch = /^([`~]{3,})/.exec(trimmed);
-    if (fenceMatch) {
-      const fence = fenceMatch[1];
-      if (fence === undefined) continue;
-      if (codeFenceOpener === null) {
-        // Opening fence: record character + length.
-        codeFenceOpener = fence;
-      } else if (
-        fence[0] === codeFenceOpener[0] &&
-        fence.length >= codeFenceOpener.length
-      ) {
-        // Closing fence: must match opener's character and be at least as long.
-        codeFenceOpener = null;
-      }
-      // Whether opening, closing, or a mismatched-character line (content inside
-      // a fence), always skip — do not try to parse as a heading.
-      continue;
-    }
-    if (codeFenceOpener !== null) continue;
-
-    // Match ATX headings at depth h2–h6. The renderer's heading-links plugin
-    // slugs h2–h6 only (h1 is never assigned an id — the frontmatter title is
-    // the page's h1), so matching h1 here would advance the shared dedup counter
-    // out of step with the renderer and break the TOC anchor for a same-text h2.
-    // Allow one or more spaces/tabs after the hashes (both valid per CommonMark).
-    const match = /^(#{2,6})[ \t]+(.+)$/.exec(line.trim());
-    if (!match) continue;
-
-    const hashes = match[1];
-    const rawText = match[2];
-    if (hashes === undefined || rawText === undefined) continue;
-
-    const depth = hashes.length;
-    // Strip inline markup to get the plain text the renderer sees, so the slug
-    // matches the heading element's rendered id attribute.
-    const text = stripInlineMarkdown(rawText.trim());
-
-    // Always allocate (advancing the dedup counter and, in hierarchical mode,
-    // the ancestor stack — maintaining parity with the renderer across all
-    // h2–h6), but only push within the configured depth window.
-    const slug = allocator.allocate(depth, text);
-    if (depth >= lo && depth <= hi) {
-      headings.push({ depth, slug, text });
-    }
-  }
-
-  return headings;
+  return _extractHeadings(body, {
+    tocMinDepth: opts?.tocMinDepth ?? settings.tocMinDepth,
+    tocMaxDepth: opts?.tocMaxDepth ?? settings.tocMaxDepth,
+    strategy: opts?.strategy ?? settings.headingIdStrategy,
+  });
 }