@takazudo/zudo-doc 0.2.21 → 1.0.0

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

@@ -0,0 +1,125 @@
+import type { DocPageEntry, DocNavNode, AutoIndexNode, DocPageBaseProps } from "../doc-page-props/index.js";
+import type { NavSourceDocs } from "../nav-source-docs/index.js";
+import type { BreadcrumbItem } from "../breadcrumb/types.js";
+import type { HeadingItem } from "../extract-headings/index.js";
+export type { DocPageEntry, DocNavNode, AutoIndexNode, DocPageBaseProps, NavSourceDocs };
+/** One enumerated doc route: a content entry or an auto-generated category
+ *  index, with all per-page derived data pre-computed. */
+export interface DocRouteEntry {
+    /** Canonical route slug ("" for the docs root index — #1891). */
+    slug: string;
+    /** Optional-catchall params array — `toSlugParams(slug)` ([] for the root). */
+    slugParams: string[];
+    /**
+     * True when the entry came from the base collection rather than the locale
+     * collection (`!localeSlugSet.has(slug)`). Only meaningful on routes whose
+     * nav source performs a locale merge — routes without one (default-locale /
+     * versioned-EN, where `localeSlugSet` is empty) must ignore this field.
+     * Always false for autoIndex items.
+     */
+    isFallback: boolean;
+    /** Shared page props (kind/entry/autoIndex/breadcrumbs/prev/next/headings). */
+    props: DocPageBaseProps;
+}
+export interface BuildDocRouteEntriesArgs {
+    /** Identity-stable nav source for this route's (locale, version) context. */
+    source: NavSourceDocs;
+    /** Active locale for nav-tree labels and breadcrumbs. */
+    locale: string;
+    /**
+     * Unique memo signature for this route context. Each route file passes its
+     * own prefix plus the loop variables (version slug / locale), e.g.
+     * "docs;en", "locale-docs;ja", "v-docs;1.0", "v-locale-docs;1.0;ja" —
+     * call sites that share a docs array identity must never collide on a key.
+     */
+    routeSig: string;
+    /** Versioned URL closure bound to the route's version (+ locale). Presence
+     *  switches the versioned behaviors (breadcrumbs, prev/next, child hrefs). */
+    urlFor?: (slug: string) => string;
+}
+export type { BreadcrumbItem, HeadingItem };
+/**
+ * Injected context for `createDocRouteEntries`.
+ */
+export interface DocRouteEntriesContext {
+    /**
+     * Build the nav tree for a locale from a flat entry array and category meta.
+     * Host passes `buildNavTree` from `@/utils/docs`.
+     */
+    buildNavTree: (docs: DocPageEntry[], locale: string, categoryMeta: Map<string, unknown>) => DocNavNode[];
+    /**
+     * Build breadcrumb trail by walking the nav tree.
+     * Host passes `buildBreadcrumbs` from `@/utils/docs`.
+     */
+    buildBreadcrumbs: (tree: DocNavNode[], slug: string, locale: string, urlFor?: (slug: string) => string) => BreadcrumbItem[];
+    /**
+     * Collect all auto-generated index nodes (categories without index.mdx).
+     * Host passes `collectAutoIndexNodes` from `@/utils/docs`.
+     */
+    collectAutoIndexNodes: (tree: DocNavNode[]) => AutoIndexNode[];
+    /**
+     * Determine the nav section (categoryMatch) for a slug.
+     * Host passes `getNavSectionForSlug` from `@/utils/nav-scope`.
+     */
+    getNavSectionForSlug: (slug: string) => string | undefined;
+    /**
+     * Filter top-level nav nodes by a categoryMatch value.
+     * Host passes `getNavSubtree` from `@/utils/nav-scope`.
+     */
+    getNavSubtree: (tree: DocNavNode[], categoryMatch?: string) => DocNavNode[];
+    /**
+     * Convert a content entry slug to a canonical route slug.
+     * Host passes `toRouteSlug` from `@/utils/slug` (or the package's
+     * `@takazudo/zudo-doc/slug`).
+     */
+    toRouteSlug: (id: string) => string;
+    /**
+     * Convert a canonical route slug to an optional-catchall params array.
+     * Host passes `toSlugParams` from `@/utils/slug`.
+     */
+    toSlugParams: (slug: string) => string[];
+    /**
+     * Extract headings from a raw MDX body.
+     * Host passes the wrapper from `pages/lib/_extract-headings.ts`.
+     */
+    extractHeadings: (body: string) => HeadingItem[];
+}
+/**
+ * Result of `createDocRouteEntries`. Contains the `buildDocRouteEntries`
+ * function bound to the injected context.
+ */
+export interface DocRouteEntriesAPI {
+    /**
+     * Enumerate all doc routes for one (locale, version) context, with per-entry
+     * derived data pre-computed. Memoized per build on the identity-stable
+     * `source.docs` array.
+     */
+    buildDocRouteEntries: (args: BuildDocRouteEntriesArgs) => DocRouteEntry[];
+}
+/**
+ * Create the `buildDocRouteEntries` function bound to the host's injected
+ * context.
+ *
+ * @example
+ * ```ts
+ * // pages/lib/_doc-route-entries.ts (thin stub)
+ * 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 { extractHeadings } from "./_extract-headings";
+ *
+ * export const { buildDocRouteEntries } = createDocRouteEntries({
+ *   buildNavTree,
+ *   buildBreadcrumbs,
+ *   collectAutoIndexNodes,
+ *   getNavSectionForSlug,
+ *   getNavSubtree,
+ *   toRouteSlug,
+ *   toSlugParams,
+ *   extractHeadings,
+ * });
+ * export type { DocRouteEntry, BuildDocRouteEntriesArgs };
+ * ```
+ */
+export declare function createDocRouteEntries(ctx: DocRouteEntriesContext): DocRouteEntriesAPI;

package/dist/doc-route-entries/index.js

@@ -0,0 +1,76 @@
+import { memoizeDerived } from "../nav-source-cache/index.js";
+import {
+  resolveDocPrevNext,
+  flattenSubtree,
+  rewriteNavHref,
+  remapNavChildHrefs
+} from "../doc-route-paths/index.js";
+function createDocRouteEntries(ctx) {
+  const {
+    buildNavTree,
+    buildBreadcrumbs,
+    collectAutoIndexNodes,
+    getNavSectionForSlug,
+    getNavSubtree,
+    toRouteSlug,
+    toSlugParams,
+    extractHeadings
+  } = ctx;
+  function buildDocRouteEntries(args) {
+    const { source, locale, routeSig, urlFor } = args;
+    return memoizeDerived([source.docs], `docRouteEntries;${routeSig}`, () => {
+      const { docs, navDocs, categoryMeta, localeSlugSet } = source;
+      const tree = buildNavTree(navDocs, locale, categoryMeta);
+      const breadcrumbTree = urlFor ? tree : buildNavTree(docs, locale, categoryMeta);
+      const result = [];
+      for (const entry of docs) {
+        if (entry.data.category_no_page === true) continue;
+        const slug = entry.data.slug ?? toRouteSlug(entry.slug);
+        const navSection = getNavSectionForSlug(slug);
+        const subtree = getNavSubtree(tree, navSection);
+        const { prev: prevNode, next: nextNode } = resolveDocPrevNext(
+          tree,
+          flattenSubtree(subtree),
+          slug,
+          entry.data
+        );
+        result.push({
+          slug,
+          slugParams: toSlugParams(slug),
+          isFallback: !localeSlugSet.has(slug),
+          props: {
+            kind: "entry",
+            entry,
+            breadcrumbs: buildBreadcrumbs(breadcrumbTree, slug, locale, urlFor),
+            prev: rewriteNavHref(prevNode, urlFor),
+            next: rewriteNavHref(nextNode, urlFor),
+            headings: extractHeadings(entry.body ?? "")
+          }
+        });
+      }
+      for (const node of collectAutoIndexNodes(tree)) {
+        result.push({
+          slug: node.slug,
+          slugParams: toSlugParams(node.slug),
+          isFallback: false,
+          props: {
+            kind: "autoIndex",
+            autoIndex: urlFor ? {
+              ...node,
+              children: remapNavChildHrefs(node.children, urlFor)
+            } : node,
+            breadcrumbs: buildBreadcrumbs(breadcrumbTree, node.slug, locale, urlFor),
+            prev: null,
+            next: null,
+            headings: []
+          }
+        });
+      }
+      return result;
+    });
+  }
+  return { buildDocRouteEntries };
+}
+export {
+  createDocRouteEntries
+};

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

@@ -0,0 +1,54 @@
+import type { DocNavNode } from "../doc-page-props/index.js";
+export type { DocNavNode };
+/**
+ * Flatten a nav tree into a pre-order traversal array.
+ * Mirrors `flattenTree` from `src/utils/docs.ts`.
+ */
+export declare function flattenTree(nodes: DocNavNode[]): DocNavNode[];
+/**
+ * Find a single nav node by slug in a tree.
+ * Mirrors `findNode` from `src/utils/docs.ts`.
+ */
+export declare function findNode(nodes: DocNavNode[], slug: string): DocNavNode | undefined;
+/** The two pagination-override fields read off entry frontmatter. */
+export interface PaginationOverrides {
+    /** `undefined` = no override; `null` = suppress; string = target slug. */
+    pagination_prev?: string | null;
+    pagination_next?: string | null;
+}
+/**
+ * Resolve prev/next nav nodes for an entry against the route's OWN nav tree.
+ *
+ * - Sequential prev/next come from the flattened sub-tree (`subtreeFlat`).
+ * - Frontmatter `pagination_prev` / `pagination_next` overrides resolve via
+ *   `findNode(tree, …)` against the SAME `tree` the route built — never a
+ *   foreign tree. The caller passes its own version/locale-scoped tree, so a
+ *   `/v/` override resolves to a `/v/` node and a latest override to a latest
+ *   node. (#1916 — pagination-override must bind to the correct tree.)
+ *
+ * Returns the raw DocNavNodes (hrefs untouched). Callers that need versioned
+ * hrefs run the result through `rewriteNavHref` with their `urlFor` closure.
+ */
+export declare function resolveDocPrevNext(tree: DocNavNode[], subtreeFlat: DocNavNode[], slug: string, overrides: PaginationOverrides): {
+    prev: DocNavNode | null;
+    next: DocNavNode | null;
+};
+/** Flatten the relevant sub-tree for an entry — convenience over flattenTree. */
+export declare function flattenSubtree(subtree: DocNavNode[]): DocNavNode[];
+/**
+ * Rewrite a single nav node's href via the route's `urlFor` closure.
+ *
+ * Returns `null` for a `null` node. Latest routes pass `undefined` (leave the
+ * href as the latest `docsUrl` already baked into the node); versioned routes
+ * pass `urlFor` so prev/next links point at the versioned URL.
+ */
+export declare function rewriteNavHref(node: DocNavNode | null, urlFor: ((slug: string) => string) | undefined): DocNavNode | null;
+/**
+ * Remap an auto-index node's child-card hrefs via `urlFor`.
+ *
+ * #1916 #2: on versioned routes the children carry latest `docsUrl` hrefs
+ * (every nav node does — see toNavNodes). They MUST be overridden to the
+ * versioned URL ALWAYS, not only when `c.href` is missing. Passing `urlFor`
+ * here does exactly that. Latest routes pass `undefined` to keep the original.
+ */
+export declare function remapNavChildHrefs(children: DocNavNode[], urlFor: ((slug: string) => string) | undefined): DocNavNode[];

package/dist/doc-route-paths/index.js

@@ -0,0 +1,61 @@
+function flattenTree(nodes) {
+  const result = [];
+  flattenInto(nodes, result);
+  return result;
+}
+function flattenInto(nodes, acc) {
+  for (const node of nodes) {
+    if (node.hasPage) acc.push(node);
+    flattenInto(node.children, acc);
+  }
+}
+function findNode(nodes, slug) {
+  for (const node of nodes) {
+    if (node.slug === slug) return node;
+    const found = findNode(node.children, slug);
+    if (found) return found;
+  }
+  return void 0;
+}
+function resolveDocPrevNext(tree, subtreeFlat, slug, overrides) {
+  const idx = subtreeFlat.findIndex((n) => n.slug === slug);
+  let prev = idx > 0 ? subtreeFlat[idx - 1] ?? null : null;
+  let next = idx >= 0 && idx < subtreeFlat.length - 1 ? subtreeFlat[idx + 1] ?? null : null;
+  if (overrides.pagination_prev !== void 0) {
+    if (overrides.pagination_prev === null) {
+      prev = null;
+    } else {
+      const found = findNode(tree, overrides.pagination_prev);
+      prev = found ?? prev;
+    }
+  }
+  if (overrides.pagination_next !== void 0) {
+    if (overrides.pagination_next === null) {
+      next = null;
+    } else {
+      const found = findNode(tree, overrides.pagination_next);
+      next = found ?? next;
+    }
+  }
+  return { prev, next };
+}
+function flattenSubtree(subtree) {
+  return flattenTree(subtree);
+}
+function rewriteNavHref(node, urlFor) {
+  if (!node) return null;
+  if (!urlFor) return node;
+  return { ...node, href: urlFor(node.slug) };
+}
+function remapNavChildHrefs(children, urlFor) {
+  if (!urlFor) return children;
+  return children.map((c) => ({ ...c, href: urlFor(c.slug) }));
+}
+export {
+  findNode,
+  flattenSubtree,
+  flattenTree,
+  remapNavChildHrefs,
+  resolveDocPrevNext,
+  rewriteNavHref
+};

package/dist/doc-tags-area/index.d.ts

@@ -0,0 +1,38 @@
+/** @jsxRuntime automatic */
+/** @jsxImportSource preact */
+import type { VNode } from "preact";
+import type { TagVocabularyEntry, TagGovernanceMode } from "../settings.js";
+/** Settings subset read by the DocTagsArea factory. */
+export interface DocTagsAreaSettings {
+    docTags: boolean;
+    tagVocabulary: boolean | readonly TagVocabularyEntry[];
+    tagGovernance: TagGovernanceMode;
+}
+/** Dependencies injected by the host stub. */
+export interface DocTagsAreaDeps {
+    settings: DocTagsAreaSettings;
+    /** Default locale code (e.g. "en"). */
+    defaultLocale: string;
+    /** Tag vocabulary entries (from the host's `@/config/tag-vocabulary`). */
+    tagVocabularyEntries: readonly TagVocabularyEntry[];
+    /**
+     * Build the base-prefixed tag detail page href for the given tag and locale.
+     * Host passes a pre-bound function using `withBase` and `defaultLocale`.
+     */
+    tagHref: (tag: string, locale: string) => string;
+    /** Translate a UI string key for a locale. */
+    t: (key: string, locale: string) => string;
+}
+export interface DocTagsAreaProps {
+    /** Page slug, e.g. "guides/sidebar". */
+    slug: string;
+    /** Active locale string, e.g. "en", "ja". */
+    locale: string;
+    /** Raw tag strings from the page frontmatter (entry.data.tags). */
+    tags: readonly string[] | undefined;
+}
+/**
+ * Create a `DocTagsArea` component bound to the host's settings and
+ * injected dependencies.
+ */
+export declare function createDocTagsArea(deps: DocTagsAreaDeps): (props: DocTagsAreaProps) => VNode | null;

package/dist/doc-tags-area/index.js

@@ -0,0 +1,30 @@
+import { jsx } from "preact/jsx-runtime";
+import { DocTags } from "../metainfo/index.js";
+import { resolvePageTags } from "../tag-helpers/index.js";
+function createDocTagsArea(deps) {
+  const { settings, tagVocabularyEntries, tagHref, t } = deps;
+  function DocTagsArea({ locale, tags }) {
+    if (!settings.docTags) return null;
+    const rawTags = tags ?? [];
+    const vocab = settings.tagVocabulary ? tagVocabularyEntries : false;
+    const canonicalTags = resolvePageTags(rawTags, vocab, settings.tagGovernance);
+    if (canonicalTags.length === 0) return null;
+    const resolvedTags = canonicalTags.map((tag) => ({
+      tag,
+      href: tagHref(tag, locale)
+    }));
+    return /* @__PURE__ */ jsx(
+      DocTags,
+      {
+        placement: "after-title",
+        tags: resolvedTags,
+        tagsLabel: t("doc.tags", locale),
+        taggedWithLabel: t("doc.taggedWith", locale)
+      }
+    );
+  }
+  return DocTagsArea;
+}
+export {
+  createDocTagsArea
+};

package/dist/doclayout/anchors.d.ts

@@ -3,7 +3,7 @@
  * the literal anchor text. This is the stable key the drift checker keys
  * off of; the surrounding comment syntax is derived from `kind`.
  */
-type DocLayoutAnchorId = "imports" | "frontmatter" | "head-scripts" | "head-links" | "header-call:start" | "header-call:end" | "after-sidebar" | "content-wrapper:start" | "content-wrapper:end" | "breadcrumb:start" | "breadcrumb:end" | "after-breadcrumb" | "after-content" | "footer" | "body-end-components" | "body-end-scripts";
+export type DocLayoutAnchorId = "imports" | "frontmatter" | "head-scripts" | "head-links" | "header-call:start" | "header-call:end" | "after-sidebar" | "content-wrapper:start" | "content-wrapper:end" | "breadcrumb:start" | "breadcrumb:end" | "after-breadcrumb" | "after-content" | "footer" | "body-end-components" | "body-end-scripts";
 /**
  * Whether the anchor lives in the frontmatter region (`---` block in
  * Astro / module-scope in JSX) or in the body markup region.
@@ -15,8 +15,8 @@ type DocLayoutAnchorId = "imports" | "frontmatter" | "head-scripts" | "head-link
  *   literal HTML form for byte-for-byte parity with the existing
  *   create-zudo-doc anchor strings).
  */
-type DocLayoutAnchorKind = "frontmatter" | "body";
-interface DocLayoutAnchor {
+export type DocLayoutAnchorKind = "frontmatter" | "body";
+export interface DocLayoutAnchor {
     readonly id: DocLayoutAnchorId;
     readonly kind: DocLayoutAnchorKind;
 }
@@ -25,7 +25,7 @@ interface DocLayoutAnchor {
  * doc-layout file. Order is informational (useful for the drift
  * checker's diagnostic output); identity is what matters.
  */
-declare const DOC_LAYOUT_ANCHORS: readonly DocLayoutAnchor[];
+export declare const DOC_LAYOUT_ANCHORS: readonly DocLayoutAnchor[];
 /**
  * Build the literal anchor *comment string* the drift checker greps for
  * in a scaffolded file.
@@ -39,17 +39,15 @@ declare const DOC_LAYOUT_ANCHORS: readonly DocLayoutAnchor[];
  *   anchorComment({ id: "footer", kind: "body" })
  *     // "<!-- @slot:doc-layout:footer -->"
  */
-declare function anchorComment(anchor: DocLayoutAnchor): string;
+export declare function anchorComment(anchor: DocLayoutAnchor): string;
 /**
  * Convenience: every anchor's comment string, in declaration order. The
  * drift checker can iterate this and assert each substring appears in the
  * scaffolded doc-layout file.
  */
-declare function allAnchorComments(): readonly string[];
+export declare function allAnchorComments(): readonly string[];
 /**
  * Convenience: anchor IDs as a typed set. Useful when a caller wants to
  * verify "is this id one of ours?" without scanning the full list.
  */
-declare const DOC_LAYOUT_ANCHOR_IDS: ReadonlySet<DocLayoutAnchorId>;
-
-export { DOC_LAYOUT_ANCHORS, DOC_LAYOUT_ANCHOR_IDS, type DocLayoutAnchor, type DocLayoutAnchorId, type DocLayoutAnchorKind, allAnchorComments, anchorComment };
+export declare const DOC_LAYOUT_ANCHOR_IDS: ReadonlySet<DocLayoutAnchorId>;

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

@@ -1,11 +1,8 @@
-import { DocLayoutProps } from './doc-layout.js';
-import { ComponentChildren, JSX } from 'preact';
-import { HeadingItem } from '../toc/types.js';
-import { VersionBannerLabels } from '../i18n-version/version-banner.js';
-export { DOC_LAYOUT_ANCHORS, DOC_LAYOUT_ANCHOR_IDS, DocLayoutAnchor, DocLayoutAnchorId, DocLayoutAnchorKind, allAnchorComments, anchorComment } from './anchors.js';
-
 /** @jsxImportSource preact */
-
+import type { ComponentChildren, JSX } from "preact";
+import { type DocLayoutProps } from "./doc-layout.js";
+import type { HeadingItem } from "../toc/types.js";
+import { type VersionBannerLabels } from "../i18n-version/version-banner.js";
 /**
  * Override slots for the default-bearing wrapper. Any slot that the
  * caller wants to replace can be passed here; otherwise the package
@@ -16,7 +13,7 @@ export { DOC_LAYOUT_ANCHORS, DOC_LAYOUT_ANCHOR_IDS, DocLayoutAnchor, DocLayoutAn
  * (link columns, copyright, taglist) pass `footerOverride` with a
  * host-side data-aware wrapper — see `pages/lib/footer-with-defaults.tsx`.
  */
-interface DocLayoutWithDefaultsProps extends Omit<DocLayoutProps, "header" | "sidebar" | "toc" | "mobileToc" | "breadcrumb" | "footer" | "main"> {
+export interface DocLayoutWithDefaultsProps extends Omit<DocLayoutProps, "header" | "sidebar" | "toc" | "mobileToc" | "breadcrumb" | "footer" | "main"> {
     /** The page's article body. Required. */
     children: ComponentChildren;
     /** Replace the default site header. */
@@ -66,7 +63,16 @@ interface DocLayoutWithDefaultsProps extends Omit<DocLayoutProps, "header" | "si
     /** Localized labels used by the version banner. */
     versionBannerLabels?: VersionBannerLabels;
 }
-
+/**
+ * The 16 `@slot:doc-layout:*` injection-anchor strings. Wraps the
+ * canonical list from `./anchors.ts` so consumers (the drift checker,
+ * tests) can verify in one place that this wrapper carries every anchor
+ * `create-zudo-doc` knows about.
+ *
+ * The values are exposed both as the literal comment strings (what the
+ * drift checker greps for) and as the structured anchor list.
+ */
+export { DOC_LAYOUT_ANCHORS, DOC_LAYOUT_ANCHOR_IDS, allAnchorComments, anchorComment, type DocLayoutAnchor, type DocLayoutAnchorId, type DocLayoutAnchorKind, } from "./anchors.js";
 /**
  * Default-bearing wrapper. Consumers who don't need composable layout
  * control reach for this; it forwards to `<DocLayout>` and inserts
@@ -78,6 +84,4 @@ interface DocLayoutWithDefaultsProps extends Omit<DocLayoutProps, "header" | "si
  * find each anchor in both places. JSX comment expressions are
  * compile-time-only and do not affect runtime output.
  */
-declare function DocLayoutWithDefaults(props: DocLayoutWithDefaultsProps): JSX.Element;
-
-export { DocLayoutWithDefaults, type DocLayoutWithDefaultsProps };
+export declare function DocLayoutWithDefaults(props: DocLayoutWithDefaultsProps): JSX.Element;

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

@@ -1,12 +1,10 @@
-import { ComponentChildren, JSX } from 'preact';
-
 /** @jsxImportSource preact */
-
+import type { ComponentChildren, JSX } from "preact";
 /**
  * Direction-and-mode metadata for the root `<html>` element. Keeps the
  * shell from depending on a project's i18n module.
  */
-interface DocLayoutHtmlAttrs {
+export interface DocLayoutHtmlAttrs {
     /** BCP-47 language tag, e.g. `"en"`, `"ja"`. Defaults to `"en"`. */
     lang?: string;
     /**
@@ -26,7 +24,7 @@ interface DocLayoutHtmlAttrs {
  * Island wrappers, server-rendered output projected through the
  * boundary, etc.).
  */
-interface DocLayoutProps extends DocLayoutHtmlAttrs {
+export interface DocLayoutProps extends DocLayoutHtmlAttrs {
     /** Page title — rendered as the `<title>` value. */
     title: string;
     /** Optional `<meta name="description">`. */
@@ -115,7 +113,7 @@ interface DocLayoutProps extends DocLayoutHtmlAttrs {
  * `id` attribute of the desktop sidebar `<aside>`. Used by consumer code
  * (e.g. sidebar-toggle island) to locate the element in the DOM.
  */
-declare const DESKTOP_SIDEBAR_ID = "desktop-sidebar";
+export declare const DESKTOP_SIDEBAR_ID = "desktop-sidebar";
 /**
  * Composable documentation-page layout shell.
  *
@@ -124,6 +122,4 @@ declare const DESKTOP_SIDEBAR_ID = "desktop-sidebar";
  * a downstream framework (e.g. `<DocLayoutWithDefaults>` or a fully
  * custom layout) decide what fills each region.
  */
-declare function DocLayout(props: DocLayoutProps): JSX.Element;
-
-export { DESKTOP_SIDEBAR_ID, DocLayout, type DocLayoutHtmlAttrs, type DocLayoutProps };
+export declare function DocLayout(props: DocLayoutProps): JSX.Element;

package/dist/doclayout/index.d.ts

@@ -1,6 +1,6 @@
-export { DESKTOP_SIDEBAR_ID, DocLayout, DocLayoutHtmlAttrs, DocLayoutProps } from './doc-layout.js';
-export { DocLayoutWithDefaults, DocLayoutWithDefaultsProps } from './doc-layout-with-defaults.js';
-export { DOC_LAYOUT_ANCHORS, DOC_LAYOUT_ANCHOR_IDS, DocLayoutAnchor, DocLayoutAnchorId, DocLayoutAnchorKind, allAnchorComments, anchorComment } from './anchors.js';
-import 'preact';
-import '../toc/types.js';
-import '../i18n-version/version-banner.js';
+export { DocLayout, DESKTOP_SIDEBAR_ID } from "./doc-layout.js";
+export type { DocLayoutProps, DocLayoutHtmlAttrs, } from "./doc-layout.js";
+export { DocLayoutWithDefaults } from "./doc-layout-with-defaults.js";
+export type { DocLayoutWithDefaultsProps } from "./doc-layout-with-defaults.js";
+export { DOC_LAYOUT_ANCHORS, DOC_LAYOUT_ANCHOR_IDS, allAnchorComments, anchorComment, } from "./anchors.js";
+export type { DocLayoutAnchor, DocLayoutAnchorId, DocLayoutAnchorKind, } from "./anchors.js";

package/dist/eject/index.d.ts

@@ -0,0 +1,33 @@
+export interface EjectableEntry {
+    /** Package subpath, e.g. `@takazudo/zudo-doc/header` */
+    packageSubpath: string;
+    /** Local destination dir, project-relative POSIX (no trailing slash) */
+    localDir: string;
+}
+export declare const EJECTABLE: Record<string, EjectableEntry>;
+export interface ZudoDocJson {
+    /** @takazudo/zudo-doc version the ejected source came from */
+    packageVersion: string;
+    /** component name → local dir (project-relative POSIX, no trailing slash) */
+    ejected: Record<string, string>;
+}
+export interface EjectOptions {
+    /** Project root to eject into. Defaults to `process.cwd()`. */
+    cwd?: string;
+    /**
+     * Injectable resolver for the installed `@takazudo/zudo-doc` package root.
+     * Defaults to resolving `@takazudo/zudo-doc/package.json` from `cwd`
+     * node_modules. Override in tests to point at a fixture.
+     */
+    resolvePackageRoot?: (cwd: string) => string;
+}
+/**
+ * Eject a single component into the project.
+ *
+ * - If already ejected (recorded in `.zudo-doc.json`): prints a notice and
+ *   exits cleanly (safe no-op — never clobbers local edits).
+ * - Otherwise: copies the TS source from the installed package's `eject/`
+ *   tree, rewires parent-relative imports, rewrites host call sites, and
+ *   records the entry in `.zudo-doc.json`.
+ */
+export declare function eject(component: string, options?: EjectOptions): Promise<void>;