@takazudo/zudo-doc 0.2.21 → 1.0.0

package/dist/integrations/llms-txt/index.d.ts

@@ -1,8 +1,33 @@
-export { LlmsTxtDevMiddlewareOptions, LlmsTxtMiddleware, LlmsTxtMiddlewareLogger, LlmsTxtNextFn, createLlmsTxtDevMiddleware } from './dev-middleware.js';
-export { emitLlmsTxt } from './emit.js';
-export { generateLlmsFullTxt, generateLlmsTxt } from './generate.js';
-export { loadDocEntries } from './load.js';
-export { stripImportsAndJsx } from './strip.js';
-export { LlmsDocEntry, LlmsTxtEmitOptions, LlmsTxtEmitResult, LlmsTxtFrontmatter, LlmsTxtLoadOptions, LlmsTxtLocaleConfig, LlmsTxtLogger, LlmsTxtSiteMeta } from './types.js';
-export { collectMdFiles, isExcluded, parseMarkdownFile, slugToUrl, stripMarkdown } from '../../md-utils/index.js';
-import 'node:http';
+/**
+ * Public entry for `@takazudo/zudo-doc/integrations/llms-txt`.
+ *
+ * Framework-agnostic build emitter that produces `dist/llms.txt` and
+ * `dist/llms-full.txt` (plus per-locale variants) with byte-identical
+ * format vs the legacy Astro integration in
+ * `src/integrations/llms-txt.ts`.
+ *
+ * Typical zfb registration (see ./README.md for the full snippet):
+ *
+ *   import { emitLlmsTxt } from "@takazudo/zudo-doc/integrations/llms-txt";
+ *
+ *   // inside a zfb plugin's onBuildDone hook
+ *   emitLlmsTxt({
+ *     outDir,
+ *     siteName: "...",
+ *     siteDescription: "...",
+ *     base: "/",
+ *     defaultLocaleDir: "src/content/docs",
+ *     locales: [{ code: "ja", dir: "src/content/docs-ja" }],
+ *   });
+ *
+ * The pure `generate*` and `loadDocEntries` helpers are exported as well
+ * so a zfb non-HTML page (`pages/llms.txt.tsx`) or a unit test can build
+ * the strings directly without touching the filesystem twice.
+ */
+export { createLlmsTxtDevMiddleware } from "./dev-middleware.js";
+export type { LlmsTxtDevMiddlewareOptions, LlmsTxtMiddleware, LlmsTxtMiddlewareLogger, LlmsTxtNextFn, } from "./dev-middleware.js";
+export { emitLlmsTxt } from "./emit.js";
+export { generateLlmsFullTxt, generateLlmsTxt, } from "./generate.js";
+export { collectMdFiles, isExcluded, loadDocEntries, parseMarkdownFile, slugToUrl, } from "./load.js";
+export { stripImportsAndJsx, stripMarkdown } from "./strip.js";
+export type { LlmsDocEntry, LlmsTxtEmitOptions, LlmsTxtEmitResult, LlmsTxtFrontmatter, LlmsTxtLoadOptions, LlmsTxtLocaleConfig, LlmsTxtLogger, LlmsTxtSiteMeta, } from "./types.js";

package/dist/integrations/llms-txt/load.d.ts

@@ -1,6 +1,3 @@
-import { LlmsTxtLoadOptions, LlmsDocEntry } from './types.js';
-export { collectMdFiles, isExcluded, parseMarkdownFile, slugToUrl } from '../../md-utils/index.js';
-
 /**
  * Filesystem loader for llms-txt content. Walks a markdown content root,
  * parses frontmatter via `gray-matter`, and emits sorted
@@ -11,7 +8,8 @@ export { collectMdFiles, isExcluded, parseMarkdownFile, slugToUrl } from '../../
  * zudo-doc#2024); they are re-exported here so the integration's public
  * surface is unchanged.
  */
-
+import type { LlmsDocEntry, LlmsTxtLoadOptions } from "./types.js";
+export { collectMdFiles, isExcluded, parseMarkdownFile, slugToUrl, } from "../../md-utils/index.js";
 /**
  * Build the sorted {@link LlmsDocEntry} list for a single content root.
  * Excluded pages (draft / unlisted / search_exclude) are dropped.
@@ -20,6 +18,4 @@ export { collectMdFiles, isExcluded, parseMarkdownFile, slugToUrl } from '../../
  * `Array.prototype.sort` is stable in V8 so ties keep filesystem
  * traversal order — same as the legacy emitter).
  */
-declare function loadDocEntries(options: LlmsTxtLoadOptions): LlmsDocEntry[];
-
-export { loadDocEntries };
+export declare function loadDocEntries(options: LlmsTxtLoadOptions): LlmsDocEntry[];

package/dist/integrations/llms-txt/strip.d.ts

@@ -1,5 +1,3 @@
-export { stripMarkdown } from '../../md-utils/index.js';
-
 /**
  * Markdown / JSX text-stripping helpers.
  *
@@ -15,12 +13,10 @@ export { stripMarkdown } from '../../md-utils/index.js';
  * (zudo-doc#2024) — and is re-exported here to keep the public surface
  * unchanged.
  */
-
+export { stripMarkdown } from "../../md-utils/index.js";
 /**
  * Strip imports, exports, and HTML/JSX tags from MDX/MD content while
  * keeping the prose layout (headings, lists, blockquotes) intact for
  * LLM consumption. Used by `llms-full.txt`.
  */
-declare function stripImportsAndJsx(content: string): string;
-
-export { stripImportsAndJsx };
+export declare function stripImportsAndJsx(content: string): string;

package/dist/integrations/llms-txt/types.d.ts

@@ -1,5 +1,3 @@
-import { MdDocFrontmatter } from '../../md-utils/index.js';
-
 /**
  * Public types for the framework-agnostic llms-txt build emitter.
  *
@@ -9,20 +7,20 @@ import { MdDocFrontmatter } from '../../md-utils/index.js';
  * markdown content roots — Astro today, zfb tomorrow, plain Node tooling
  * in a unit test, etc.
  */
-
+import type { MdDocFrontmatter } from "../../md-utils/index.js";
 /**
  * Frontmatter fields the loader reads off of each MDX/MD file. Callers
  * are free to extend this; unrecognised fields are ignored. Alias of the
  * shared {@link MdDocFrontmatter} shape (`md-utils`, zudo-doc#2024) —
  * search-index and llms-txt read the same fields.
  */
-type LlmsTxtFrontmatter = MdDocFrontmatter;
+export type LlmsTxtFrontmatter = MdDocFrontmatter;
 /**
  * One entry in the generated llms.txt / llms-full.txt files. Pure data,
  * already sorted, already stripped — generators (`generateLlmsTxt`,
  * `generateLlmsFullTxt`) consume this without further processing.
  */
-interface LlmsDocEntry {
+export interface LlmsDocEntry {
     /** Page title (frontmatter `title`, with the slug as a fallback). */
     title: string;
     /**
@@ -49,7 +47,7 @@ interface LlmsDocEntry {
  * `siteName` / `siteDescription` fields on the legacy settings object
  * one-for-one so callers can pass `settings` straight through.
  */
-interface LlmsTxtSiteMeta {
+export interface LlmsTxtSiteMeta {
     siteName: string;
     siteDescription: string;
 }
@@ -58,7 +56,7 @@ interface LlmsTxtSiteMeta {
  * represented separately on {@link LlmsTxtEmitOptions}; this type
  * describes the *additional* locales (e.g. `ja`).
  */
-interface LlmsTxtLocaleConfig {
+export interface LlmsTxtLocaleConfig {
     /** Locale code used as both the URL segment and the output subfolder. */
     code: string;
     /** Absolute or cwd-relative path to the locale's content root. */
@@ -67,7 +65,7 @@ interface LlmsTxtLocaleConfig {
 /**
  * Options for {@link loadDocEntries} — one content directory at a time.
  */
-interface LlmsTxtLoadOptions {
+export interface LlmsTxtLoadOptions {
     /** Absolute or cwd-relative path to the markdown content root. */
     contentDir: string;
     /**
@@ -94,7 +92,7 @@ interface LlmsTxtLoadOptions {
  * module so that a one-line registration in `zfb.config.ts` (or a
  * `b4-build` hook in Astro) can wire the same behaviour.
  */
-interface LlmsTxtEmitOptions extends LlmsTxtSiteMeta {
+export interface LlmsTxtEmitOptions extends LlmsTxtSiteMeta {
     /** Absolute output directory — typically `dist/`. */
     outDir: string;
     /** URL base used when materialising per-page links. */
@@ -123,16 +121,14 @@ interface LlmsTxtEmitOptions extends LlmsTxtSiteMeta {
  * `logger` and `console`. Only `info` is used today; the wider shape is
  * provided so the option can hold either object without type acrobatics.
  */
-interface LlmsTxtLogger {
+export interface LlmsTxtLogger {
     info: (msg: string) => void;
 }
 /**
  * Result returned by {@link emitLlmsTxt}. Useful for tests and for
  * callers that want to log / further process the emitted set.
  */
-interface LlmsTxtEmitResult {
+export interface LlmsTxtEmitResult {
     /** Absolute paths of every file written, in emit order. */
     written: string[];
 }
-
-export type { LlmsDocEntry, LlmsTxtEmitOptions, LlmsTxtEmitResult, LlmsTxtFrontmatter, LlmsTxtLoadOptions, LlmsTxtLocaleConfig, LlmsTxtLogger, LlmsTxtSiteMeta };

package/dist/integrations/search-index/build-emitter.d.ts

@@ -1,6 +1,5 @@
-import { SearchIndexConfig, SearchIndexEntry } from './types.js';
-
-interface SearchIndexBuildResult {
+import type { SearchIndexConfig, SearchIndexEntry } from "./types.js";
+export interface SearchIndexBuildResult {
     /** Absolute path of the JSON file that was written. */
     jsonPath: string;
     /** Number of entries serialised. */
@@ -8,7 +7,7 @@ interface SearchIndexBuildResult {
     /** The raw entries — exposed so callers can pipe the same data into a Worker bundle if needed. */
     entries: SearchIndexEntry[];
 }
-interface SearchIndexBuildOptions extends SearchIndexConfig {
+export interface SearchIndexBuildOptions extends SearchIndexConfig {
     /** Absolute path of the build output directory (e.g. zfb's `outDir`). */
     outDir: string;
     /** Optional logger; defaults to a no-op so builds stay quiet by default. */
@@ -25,6 +24,4 @@ interface SearchIndexBuildOptions extends SearchIndexConfig {
  * Schema is byte-identical to today's Astro integration — see
  * `types.ts` for the locked-in shape.
  */
-declare function emitSearchIndex(options: SearchIndexBuildOptions): SearchIndexBuildResult;
-
-export { type SearchIndexBuildOptions, type SearchIndexBuildResult, emitSearchIndex };
+export declare function emitSearchIndex(options: SearchIndexBuildOptions): SearchIndexBuildResult;

package/dist/integrations/search-index/collect.d.ts

@@ -1,5 +1,4 @@
-import { SearchIndexConfig, SearchIndexEntry } from './types.js';
-
+import { type SearchIndexConfig, type SearchIndexEntry } from "./types.js";
 /**
  * Collect every search-index entry across the default locale plus all
  * configured non-default locales. The traversal order matches today's
@@ -7,6 +6,4 @@ import { SearchIndexConfig, SearchIndexEntry } from './types.js';
  * order of the `locales` map. Downstream consumers should not rely on
  * order beyond that, but keep it stable for diff-friendly builds.
  */
-declare function collectSearchEntries(config: SearchIndexConfig): SearchIndexEntry[];
-
-export { collectSearchEntries };
+export declare function collectSearchEntries(config: SearchIndexConfig): SearchIndexEntry[];

package/dist/integrations/search-index/dev-middleware.d.ts

@@ -1,8 +1,7 @@
-import { IncomingMessage, ServerResponse } from 'node:http';
-import { SearchIndexConfig } from './types.js';
-
-type SearchIndexNextFn = (err?: unknown) => void;
-type SearchIndexMiddleware = (req: IncomingMessage, res: ServerResponse, next: SearchIndexNextFn) => void;
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { type SearchIndexConfig } from "./types.js";
+export type SearchIndexNextFn = (err?: unknown) => void;
+export type SearchIndexMiddleware = (req: IncomingMessage, res: ServerResponse, next: SearchIndexNextFn) => void;
 /**
  * Build a dev-server middleware that responds to GET requests for
  * `/search-index.json` (or any URL ending in that suffix, mirroring the
@@ -11,6 +10,4 @@ type SearchIndexMiddleware = (req: IncomingMessage, res: ServerResponse, next: S
  * index from disk — that matches the Astro behaviour and keeps content
  * edits visible without a dev-server restart.
  */
-declare function createSearchIndexDevMiddleware(config: SearchIndexConfig): SearchIndexMiddleware;
-
-export { type SearchIndexMiddleware, type SearchIndexNextFn, createSearchIndexDevMiddleware };
+export declare function createSearchIndexDevMiddleware(config: SearchIndexConfig): SearchIndexMiddleware;

package/dist/integrations/search-index/index.d.ts

@@ -1,5 +1,7 @@
-export { SearchIndexBuildOptions, SearchIndexBuildResult, emitSearchIndex } from './build-emitter.js';
-export { collectSearchEntries } from './collect.js';
-export { SearchIndexMiddleware, SearchIndexNextFn, createSearchIndexDevMiddleware } from './dev-middleware.js';
-export { MAX_BODY_LENGTH, SEARCH_INDEX_ROUTE, SearchIndexConfig, SearchIndexEntry, SearchIndexLocaleConfig } from './types.js';
-import 'node:http';
+export { emitSearchIndex } from "./build-emitter.js";
+export type { SearchIndexBuildOptions, SearchIndexBuildResult, } from "./build-emitter.js";
+export { collectSearchEntries } from "./collect.js";
+export { createSearchIndexDevMiddleware } from "./dev-middleware.js";
+export type { SearchIndexMiddleware, SearchIndexNextFn, } from "./dev-middleware.js";
+export { MAX_BODY_LENGTH, SEARCH_INDEX_ROUTE, } from "./types.js";
+export type { SearchIndexConfig, SearchIndexEntry, SearchIndexLocaleConfig, } from "./types.js";

package/dist/integrations/search-index/types.d.ts

@@ -4,7 +4,7 @@
  * consumers (the search client island and packages/search-worker via
  * MiniSearch) keep working unchanged after the zfb cutover.
  */
-interface SearchIndexEntry {
+export interface SearchIndexEntry {
     /** Stable identifier — `slug` for the default locale, `${locale}/${slug}` otherwise. */
     id: string;
     /** Frontmatter title, falling back to the slug when missing. */
@@ -17,12 +17,12 @@ interface SearchIndexEntry {
     description: string;
 }
 /** A locale entry that mirrors the Astro `settings.locales` shape we already have. */
-interface SearchIndexLocaleConfig {
+export interface SearchIndexLocaleConfig {
     /** Absolute or project-relative directory holding this locale's MDX content. */
     dir: string;
 }
 /** Build-time configuration for collecting search entries. */
-interface SearchIndexConfig {
+export interface SearchIndexConfig {
     /** Default-locale content directory (e.g. `src/content/docs`). */
     docsDir: string;
     /** Optional non-default locales, keyed by locale code (e.g. `{ ja: { dir: "src/content/docs-ja" } }`). */
@@ -31,8 +31,6 @@ interface SearchIndexConfig {
     base?: string;
 }
 /** Maximum body text stored per entry (display excerpt cap). */
-declare const MAX_BODY_LENGTH = 300;
+export declare const MAX_BODY_LENGTH = 300;
 /** Public route the dev middleware and build emitter agree on. */
-declare const SEARCH_INDEX_ROUTE = "/search-index.json";
-
-export { MAX_BODY_LENGTH, SEARCH_INDEX_ROUTE, type SearchIndexConfig, type SearchIndexEntry, type SearchIndexLocaleConfig };
+export declare const SEARCH_INDEX_ROUTE = "/search-index.json";

package/dist/island-types/index.d.ts

@@ -0,0 +1,44 @@
+/** A single turn in the AI-chat conversation. */
+export interface ChatMessage {
+    role: "user" | "assistant";
+    content: string;
+}
+/** A single git revision entry for a document. */
+export interface DocHistoryEntry {
+    /** Full commit hash (use .slice(0, 7) for display). */
+    hash: string;
+    /** ISO 8601 date string. */
+    date: string;
+    /** Commit author name. */
+    author: string;
+    /** First line of commit message. */
+    message: string;
+    /** Full file content at this revision. */
+    content: string;
+}
+/** Complete history data for a single document. */
+export interface DocHistoryData {
+    /** Document slug (route path). */
+    slug: string;
+    /** Relative file path in the repository. */
+    filePath: string;
+    /** Git revision entries, newest first. */
+    entries: DocHistoryEntry[];
+}
+/** Shared inline style centering an enlarge `<dialog>` transform-free. */
+export declare const ENLARGE_DIALOG_STYLE: {
+    readonly position: "fixed";
+    readonly inset: "0";
+    readonly margin: "auto";
+};
+/** Class string for the image-enlarge `<dialog>` (hydrated + SSR fallback). */
+export declare const IMAGE_ENLARGE_DIALOG_CLASS = "zd-enlarge-dialog z-modal mx-auto max-h-[90vh] max-w-[90vw] overflow-hidden border border-muted bg-surface p-0 backdrop:z-modal-backdrop";
+/** Class string for the mermaid-enlarge `<dialog>` (hydrated + SSR fallback). */
+export declare const MERMAID_ENLARGE_DIALOG_CLASS = "zd-mermaid-dialog z-modal mx-auto h-[90vh] max-h-[90vh] w-[90vw] max-w-[90vw] overflow-hidden border border-muted bg-surface p-0 backdrop:z-modal-backdrop";
+/** Shared shape an enlarge `<dialog>` is rendered with. */
+export interface EnlargeDialogProps {
+    /** Tailwind class string for the `<dialog>`. */
+    className: string;
+    /** Inline style centering the dialog transform-free. */
+    style: typeof ENLARGE_DIALOG_STYLE;
+}

package/dist/island-types/index.js

@@ -0,0 +1,12 @@
+const ENLARGE_DIALOG_STYLE = {
+  position: "fixed",
+  inset: "0",
+  margin: "auto"
+};
+const IMAGE_ENLARGE_DIALOG_CLASS = "zd-enlarge-dialog z-modal mx-auto max-h-[90vh] max-w-[90vw] overflow-hidden border border-muted bg-surface p-0 backdrop:z-modal-backdrop";
+const MERMAID_ENLARGE_DIALOG_CLASS = "zd-mermaid-dialog z-modal mx-auto h-[90vh] max-h-[90vh] w-[90vw] max-w-[90vw] overflow-hidden border border-muted bg-surface p-0 backdrop:z-modal-backdrop";
+export {
+  ENLARGE_DIALOG_STYLE,
+  IMAGE_ENLARGE_DIALOG_CLASS,
+  MERMAID_ENLARGE_DIALOG_CLASS
+};

package/dist/locale-merge/index.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Minimal structural interface for a docs entry.
+ *
+ * Structurally compatible with the host's `DocsEntry` from
+ * `@/types/docs-entry`. Callers pass their concrete entry arrays and
+ * TypeScript's structural typing ensures compatibility.
+ */
+export interface MergeDocsEntry {
+    id: string;
+    data: {
+        slug?: string;
+        unlisted?: boolean;
+        [key: string]: unknown;
+    };
+}
+/**
+ * Options for mergeLocaleDocs.
+ *
+ * The generic parameter `T` allows callers to pass arrays of a concrete entry
+ * subtype and get back results of the same subtype, eliminating `as unknown as`
+ * casts at call sites.
+ */
+export interface MergeLocaleDocsOptions<T extends MergeDocsEntry = MergeDocsEntry> {
+    /** Pre-loaded base (EN/default-locale) docs array, already draft-filtered. */
+    baseDocs: T[];
+    /** Pre-loaded locale-specific docs array, already draft-filtered. */
+    localeDocs: T[];
+    /**
+     * When true, base docs whose path matches a `defaultLocaleOnlyPrefixes`
+     * entry are excluded from the merge result. This matches the behavior of the
+     * inline copies in route-enumerators, nav helpers, and page paths() sections.
+     *
+     * Pass true for any call site that enumerates routes or builds nav trees for
+     * non-default locales (where showing a default-locale-only page to a locale
+     * user would be incorrect). Pass false (or omit) for call sites where the
+     * filtered paths are harmless — e.g. category nav cards, taglist columns.
+     *
+     * @default false
+     */
+    applyDefaultLocaleOnlyFilter?: boolean;
+    /**
+     * Controls whether `unlisted: true` docs survive the merge.
+     *
+     * - `true`  — unlisted docs are RETAINED (locale + base). Route/sitemap
+     *             enumeration uses this: unlisted pages have real HTML files, so
+     *             they must be built; nav callers rely on `isNavVisible`
+     *             downstream to hide them from the tree.
+     * - `false` (default) — unlisted docs are DROPPED from both locale and base.
+     *             Tag aggregation uses this so hidden pages don't contribute tags.
+     *
+     * @default false
+     */
+    keepUnlisted?: boolean;
+    /**
+     * Host-injected predicate: returns true when a path should be excluded from
+     * the non-default-locale merge (i.e. it belongs to the default locale only).
+     *
+     * Only called when `applyDefaultLocaleOnlyFilter` is true. The host stub
+     * passes `isDefaultLocaleOnlyPath` from `@/utils/base`.
+     *
+     * When omitted (or when `applyDefaultLocaleOnlyFilter` is false), no path
+     * filtering is applied.
+     *
+     * Example: host passes `(path) => isDefaultLocaleOnlyPath(path)` where
+     * `isDefaultLocaleOnlyPath` is from `src/utils/base.ts`.
+     */
+    isDefaultLocaleOnlyPath?: (path: string) => boolean;
+}
+/**
+ * Result of mergeLocaleDocs.
+ *
+ * **Array identity:** Each call returns a fresh array — no module-level
+ * memoization is applied. If a caller keys a cache on the docs array identity
+ * (e.g. a nav-tree cache), it should memoize the result itself rather than
+ * relying on reference stability from this helper.
+ *
+ * This contract is intentionally unchanged from the original. The
+ * identity-stable layer for nav-source arrays lives ABOVE this helper:
+ * `pages/lib/_nav-source-docs.ts` memoizes the merge result on the
+ * snapshot-anchored input arrays + option signature (see
+ * `pages/lib/_nav-source-cache.ts`), so `mergeLocaleDocs` itself stays a pure,
+ * memo-free function (#1902).
+ *
+ * The generic `T` mirrors the parameter on {@link MergeLocaleDocsOptions} so
+ * the returned `docs` array preserves the subtype of the input arrays.
+ */
+export interface MergeLocaleDocsResult<T extends MergeDocsEntry = MergeDocsEntry> {
+    /**
+     * Merged doc array: locale docs first, followed by base docs for slugs not
+     * present in the locale collection (and not excluded by filter options).
+     */
+    docs: T[];
+    /**
+     * Set of slugs that came from the locale collection.
+     * Useful for callers that need to determine whether a page is a fallback
+     * (i.e. `isFallback = !localeSlugSet.has(slug)`).
+     */
+    localeSlugSet: ReadonlySet<string>;
+}
+/**
+ * Merge locale docs with base-locale fallbacks.
+ *
+ * Locale docs take priority; base docs fill in slugs not covered by the locale
+ * collection. Optionally excludes default-locale-only paths and/or unlisted pages.
+ *
+ * **Slug keying**: slug identity uses `d.data.slug ?? d.id`. Since `loadDocs`
+ * already strips the `/index` suffix (via `stripIndexSuffix` in `pages/_data.ts`),
+ * this key is consistent across all call sites regardless of whether they
+ * loaded docs via `loadDocs` or `bridgeEntries`.
+ *
+ * **Array identity**: returns a fresh array on each call — see
+ * {@link MergeLocaleDocsResult} for caching guidance.
+ */
+export declare function mergeLocaleDocs<T extends MergeDocsEntry = MergeDocsEntry>(options: MergeLocaleDocsOptions<T>): MergeLocaleDocsResult<T>;

package/dist/locale-merge/index.js

@@ -0,0 +1,27 @@
+function mergeLocaleDocs(options) {
+  const {
+    baseDocs,
+    localeDocs,
+    applyDefaultLocaleOnlyFilter = false,
+    keepUnlisted = false,
+    isDefaultLocaleOnlyPath
+  } = options;
+  const filteredLocale = keepUnlisted ? localeDocs : localeDocs.filter((d) => !d.data.unlisted);
+  const filteredBase = keepUnlisted ? baseDocs : baseDocs.filter((d) => !d.data.unlisted);
+  const localeSlugSet = new Set(filteredLocale.map((d) => d.data.slug ?? d.id));
+  let fallbackDocs = filteredBase.filter(
+    (d) => !localeSlugSet.has(d.data.slug ?? d.id)
+  );
+  if (applyDefaultLocaleOnlyFilter && isDefaultLocaleOnlyPath) {
+    fallbackDocs = fallbackDocs.filter(
+      (d) => !isDefaultLocaleOnlyPath(`/docs/${d.data.slug ?? d.id}`)
+    );
+  }
+  return {
+    docs: [...filteredLocale, ...fallbackDocs],
+    localeSlugSet
+  };
+}
+export {
+  mergeLocaleDocs
+};

package/dist/math-block/index.d.ts

@@ -0,0 +1,18 @@
+/** @jsxRuntime automatic */
+/** @jsxImportSource preact */
+import type { VNode } from "preact";
+export interface MathBlockProps {
+    /** Raw LaTeX source string. */
+    latex: string;
+    /** When true, renders as a block (display) equation; otherwise inline. */
+    block?: boolean;
+}
+/**
+ * Server-rendered KaTeX math component.
+ *
+ * Block mode wraps the output in `<div class="math math-display">`;
+ * inline mode uses `<span class="math math-inline">`. The class names
+ * match the standard rehype-katex output so existing CSS (e.g. the
+ * KaTeX stylesheet) still applies.
+ */
+export declare function MathBlock({ latex, block }: MathBlockProps): VNode;

package/dist/math-block/index.js

@@ -0,0 +1,29 @@
+import { jsx } from "preact/jsx-runtime";
+import katex from "katex";
+function MathBlock({ latex, block = false }) {
+  const html = katex.renderToString(latex, {
+    displayMode: block,
+    // Never throw — malformed LaTeX renders a visible error span instead
+    // of crashing the entire page build.
+    throwOnError: false
+  });
+  if (block) {
+    return /* @__PURE__ */ jsx(
+      "div",
+      {
+        class: "math math-display",
+        dangerouslySetInnerHTML: { __html: html }
+      }
+    );
+  }
+  return /* @__PURE__ */ jsx(
+    "span",
+    {
+      class: "math math-inline",
+      dangerouslySetInnerHTML: { __html: html }
+    }
+  );
+}
+export {
+  MathBlock
+};

package/dist/md-utils/index.d.ts

@@ -3,7 +3,7 @@
  * keys pass through via the index signature. Mirrors the host project's
  * docs schema (`src/config/docs-schema.ts`) for the fields listed here.
  */
-interface MdDocFrontmatter {
+export interface MdDocFrontmatter {
     title?: string;
     description?: string;
     /**
@@ -37,7 +37,7 @@ interface MdDocFrontmatter {
  * pipeline leaked into descriptions (zudo-doc#2175). Do not add other new
  * rules without also updating the byte-equality fixtures (topic-plugin-audit).
  */
-declare function stripMarkdown(md: string): string;
+export declare function stripMarkdown(md: string): string;
 /**
  * Walk `dir` recursively and return every `*.md` / `*.mdx` file's
  * absolute path together with its filesystem-derived slug. Files (or
@@ -46,7 +46,7 @@ declare function stripMarkdown(md: string): string;
  * them are not built as pages, so emitting them would yield entries
  * whose links 404.
  */
-declare function collectMdFiles(dir: string): Array<{
+export declare function collectMdFiles(dir: string): Array<{
     filePath: string;
     slug: string;
 }>;
@@ -59,12 +59,12 @@ declare function collectMdFiles(dir: string): Array<{
  * Callers must pass the EFFECTIVE slug (`data.slug ?? filesystem slug`) —
  * the frontmatter override is resolved at the call site, not here.
  */
-declare function slugToUrl(slug: string, locale: string | null, base: string, siteUrl?: string): string;
+export declare function slugToUrl(slug: string, locale: string | null, base: string, siteUrl?: string): string;
 /**
  * Parse a markdown file into frontmatter + body. Returns `null` when
  * the file is unreadable so callers can simply skip it.
  */
-declare function parseMarkdownFile(filePath: string): {
+export declare function parseMarkdownFile(filePath: string): {
     data: MdDocFrontmatter;
     content: string;
 } | null;
@@ -73,6 +73,4 @@ declare function parseMarkdownFile(filePath: string): {
  * unlisted, or a `category_no_page` metadata-only category index (no
  * built route to link to).
  */
-declare function isExcluded(data: MdDocFrontmatter): boolean;
-
-export { type MdDocFrontmatter, collectMdFiles, isExcluded, parseMarkdownFile, slugToUrl, stripMarkdown };
+export declare function isExcluded(data: MdDocFrontmatter): boolean;

package/dist/md-utils/index.js

@@ -1,6 +1,7 @@
 import { readFileSync, readdirSync } from "node:fs";
 import { join, relative } from "node:path";
 import matter from "gray-matter";
+import { toRouteSlug } from "../slug/index.js";
 function stripMarkdown(md) {
   return md.replace(/```[\s\S]*?```/g, "").replace(/`[^`]+`/g, "").replace(/\{\/\*[\s\S]*?\*\/\}/g, "").replace(/<[^>]+>/g, "").replace(/^#{1,6}\s+/gm, "").replace(/\*{1,3}([^*]+)\*{1,3}/g, "$1").replace(/_{1,3}([^_]+)_{1,3}/g, "$1").replace(/!\[[^\]]*\]\([^)]+\)/g, "").replace(/\[([^\]]+)\]\([^)]+\)/g, "$1").replace(/^>\s+/gm, "").replace(/^[-*_]{3,}\s*$/gm, "").replace(/^[\s]*[-*+]\s+/gm, "").replace(/^[\s]*\d+\.\s+/gm, "").replace(/^import\s+.*$/gm, "").replace(/^export\s+.*$/gm, "").replace(/\n{3,}/g, "\n\n").trim();
 }
@@ -19,7 +20,7 @@ function collectMdFiles(dir) {
         if (entry.name.startsWith("_")) continue;
         walk(fullPath, baseDir);
       } else if (/\.mdx?$/.test(entry.name) && !entry.name.startsWith("_")) {
-        const rel = relative(baseDir, fullPath).replace(/\.mdx?$/, "").replace(/\/index$/, "").replace(/^index$/, "");
+        const rel = toRouteSlug(relative(baseDir, fullPath).replace(/\.mdx?$/, ""));
         results.push({ filePath: fullPath, slug: rel });
       }
     }

package/dist/mdx-components/index.d.ts

@@ -0,0 +1,46 @@
+import type { Settings } from "../settings.js";
+/** Any Preact-renderable component (function returning a VNode/children). */
+type AnyComponent = (props: Record<string, unknown>) => unknown;
+/**
+ * The 4 host-supplied, locale-aware nav wrappers. Each accepts a `lang` prop;
+ * the factory injects the active `locale` so the wrapper queries the correct
+ * collection. `SiteTreeNav` is reused for both the `SiteTreeNav` and
+ * `SiteTreeNavDemo` MDX tags (matching the showcase mapping).
+ */
+export interface MdxNavData {
+    CategoryNav: AnyComponent;
+    CategoryTreeNav: AnyComponent;
+    SiteTreeNav: AnyComponent;
+}
+export interface CreateMdxComponentsOptions {
+    /**
+     * The host's resolved settings object. Read for `base` (img rewrite),
+     * `imageEnlarge` (enlargeable-`p`). Only these fields are consumed here.
+     */
+    settings: Pick<Settings, "base" | "imageEnlarge">;
+    /**
+     * Active locale for this render. Injected into each `navData` wrapper as the
+     * `lang` prop so `/ja` pages resolve the JA collection. Load-bearing — do not
+     * drop it.
+     */
+    locale: string;
+    /** Host-supplied locale-aware nav wrappers. */
+    navData: MdxNavData;
+    /**
+     * Further host-bound bindings, spread LAST so the host always wins. Typical
+     * contents: `HtmlPreview`, `Details`, `Island`, `PresetGenerator`, and the
+     * showcase stubs (`Avatar`/`Button`/`Card`/…).
+     */
+    extras?: Record<string, unknown>;
+}
+/**
+ * Build the locale-bound MDX components map.
+ *
+ * Called once per page render with the active `locale`. Bakes all
+ * package-resident components and threads `locale` into the host-supplied
+ * `navData` wrappers (the /ja-correctness mechanism), then spreads `extras`
+ * last so host bindings (HtmlPreview, Details, Island, PresetGenerator,
+ * showcase stubs) win over any same-named default.
+ */
+export declare function createMdxComponents(options: CreateMdxComponentsOptions): Record<string, unknown>;
+export {};