@takazudo/zfb 2.5.2 → 2.6.0

package/dist/config.d.ts

@@ -262,6 +262,33 @@ export type ZfbConfig = {
      * Mirrors `Config::strict_content_bridge` in `crates/zfb/src/config.rs`.
      */
     strictContentBridge?: boolean;
+    /**
+     * Whether `zfb build` writes a JSON render artifact for every
+     * markdown/MDX-backed HTML route whose rendered page contains exactly
+     * one top-level content region — the content-region HTML as shipped,
+     * compiler-allocated headings with slugs, a contract version, and a
+     * raw-source digest (Render Artifact Export epic #2421). The extraction
+     * pass and artifact writer are Rust-side
+     * (`crate::commands::render_artifact::export_render_artifacts`),
+     * running between the link-base rewrite and HTML minification. See the
+     * [Render Artifacts docs](https://github.com/Takazudo/zudo-front-builder/blob/main/docs/src/content/docs/concepts/render-artifacts.mdx)
+     * for the full JSON contract.
+     *
+     * This is the effective boolean the CLI's `--emit-render-artifacts` /
+     * `--no-emit-render-artifacts` tri-state resolves against. Precedence:
+     * explicit CLI flag > this config field > default `false`.
+     *
+     * Default: `false` (explicit opt-in), unlike `emitRoutesManifest`'s
+     * default-on posture — the writer instruments every rendered region
+     * with sentinel markers before stripping them back out, and the epic
+     * keeps that opt-in until the confirm sub-issue proves flag-off output
+     * stays byte-identical.
+     *
+     * Build-only: it does not affect `zfb dev`.
+     *
+     * Mirrors `Config::emit_render_artifacts` in `crates/zfb/src/config.rs`.
+     */
+    emitRenderArtifacts?: boolean;
     /**
      * Bundler options. `bundle.exclude` lists project-relative globs of
      * source files to keep out of the esbuild graph (e.g.

package/dist/config.js.map

@@ -1 +1 @@
-{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,iEAAiE;AACjE,EAAE;AACF,kEAAkE;AAClE,qEAAqE;AACrE,uEAAuE;AACvE,oEAAoE;AACpE,+BAA+B;AAC/B,EAAE;AACF,yEAAyE;AACzE,uEAAuE;AACvE,uEAAuE;AACvE,kEAAkE;AAClE,EAAE;AACF,uEAAuE;AACvE,uEAAuE;AAmyCvE;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,MAAiB;IAC5C,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,YAAY,CAC1B,aAAqB,EACrB,MAA0B;IAE1B,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACpB,OAAO,MAAM,CAAC;IAChB,CAAC;IACD,OAAO;QACL,GAAG,MAAM;QACT,OAAO,EAAE,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE;YACrC,IAAI,MAAM,KAAK,IAAI,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;gBAC5E,wEAAwE;gBACxE,mEAAmE;gBACnE,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,GAAG,MAAM,EAAE,CAAC;YACtD,CAAC;YACD,OAAO,MAAM,CAAC;QAChB,CAAC,CAAC;KACH,CAAC;AACJ,CAAC","sourcesContent":["// `zfb/config` — TypeScript helper for the `zfb.config.ts` form.\n//\n// The zfb config loader (`crates/zfb/src/config.rs`) accepts both\n// `zfb.config.ts` and `zfb.config.json`; TS wins when both files are\n// present. JSON remains accepted for projects predating the TS loader,\n// while new projects should prefer the TS form for editor types and\n// `defineConfig` autocomplete.\n//\n// At parse time, zfb bundles the user's `zfb.config.ts` with esbuild and\n// aliases this `zfb/config` import to an internal stub that re-exports\n// `defineConfig` as the identity function — so a user project does not\n// need the `zfb` npm package installed locally just to be parsed.\n//\n// The shape mirrors the Rust `Config` struct one-for-one. Keep them in\n// sync; the `defineConfig` identity helper is the single anchor point.\n\nexport type Framework = \"preact\" | \"react\";\n\nexport type CollectionDef = {\n  /** Identifier used at the call site (e.g. `\"blog\"`). */\n  name: string;\n  /** Directory (relative to the project root) holding the entries. */\n  path: string;\n  /** Optional schema. Enforced by `zfb check`. */\n  schema?: Record<string, unknown>;\n  /**\n   * Optional include globs (Astro-style, evaluated relative to `path`).\n   * When set and non-empty, an entry is kept only if at least one\n   * pattern matches its relative path. When omitted or empty, no\n   * include-filtering happens. Patterns use the `globset` dialect\n   * (Unix-style: `*`, `**`, `?`, `[…]`).\n   */\n  include?: string[];\n  /**\n   * Optional exclude globs. When set, an entry is dropped if any\n   * pattern matches its relative path. Evaluated AFTER `include`.\n   * Together they mirror Astro's `['**\\/*.mdx', '!**\\/*.en.mdx']`\n   * convention (zfb splits the negative side into its own field).\n   */\n  exclude?: string[];\n  /**\n   * Optional suffix to strip from each kept entry's slug + module\n   * specifier. Use with multi-locale layouts where one source\n   * directory holds both `foo.mdx` (default locale) and `foo.en.mdx`\n   * (locale override) — set `idStripSuffix: \".en\"` so the EN\n   * collection's slugs round-trip as `foo` instead of `foo.en`.\n   */\n  idStripSuffix?: string;\n  /**\n   * Opt-in to a `path` that escapes the project root via `..` (e.g. a\n   * monorepo-shared content dir living outside this package). Default\n   * `false` keeps the standard project-root guard. Absolute paths and\n   * Windows drive-relative/prefix forms are rejected regardless of\n   * this flag — only `..`-relative escapes are relaxed.\n   *\n   * Security note: if this collection comes from a preset, the preset\n   * author — not the consuming project — controls `path`. Setting\n   * `allowOutsideRoot: true` on a preset-provided collection widens\n   * the project's read surface to wherever that preset points, so\n   * treat it the same as any other preset-granted filesystem access.\n   */\n  allowOutsideRoot?: boolean;\n};\n\nexport type TailwindConfig = {\n  /** Whether Tailwind is enabled. Default: `true`. */\n  enabled?: boolean;\n};\n\n/**\n * Prefetch options. Mirrors `PrefetchConfig` in `crates/zfb/src/config.rs`.\n */\nexport type PrefetchConfig = {\n  /**\n   * Disable prefetch entirely.\n   *\n   * When `true`, the bundler emits `globalThis.__zfb.prefetchDisabled = true`\n   * in `entry.mjs`, and `<ClientRouter />` renders\n   * `<meta name=\"zfb-prefetch-disabled\" content=\"true\">` in `<head>`.\n   * The sibling prefetch-core module reads that meta tag at `init()` time\n   * and short-circuits — no prefetch wiring runs.\n   *\n   * The flag is site-wide and static — set once at bundle-emit time,\n   * never recomputed per-page. Default: `false`.\n   */\n  disabled?: boolean;\n};\n\n/**\n * Bundler options. Mirrors `BundleConfig` in `crates/zfb/src/config.rs`.\n */\nexport type BundleConfig = {\n  /**\n   * Project-relative glob patterns (gitignore-style) for source files\n   * the bundler must NOT pull into the esbuild graph.\n   *\n   * Why this exists: an eager `import.meta.glob('components/**\\/*.stories.tsx',\n   * { eager: true })` expands to a static import of every matched file. If a\n   * matched file imports a CJS-only package whose `package.json` resolves only\n   * via `main`/`module` or a `require`-only `exports` condition (e.g.\n   * `msw` → `path-to-regexp@6`), esbuild — invoked with `--platform=neutral`\n   * for the worker bundle — rejects it with \"Could not resolve … Main fields\n   * must be configured explicitly when using the neutral platform.\" Listing the\n   * offending file here keeps the migration build green.\n   *\n   * Each pattern is matched against the file's path RELATIVE TO THE PROJECT\n   * ROOT, in POSIX form (e.g. `components/Foo.stories.tsx` or\n   * `components/**\\/*.stories.tsx`). A matched file is:\n   *\n   * - never copied/symlinked into the bundler's shadow tree, and\n   * - dropped from any eager `import.meta.glob(...)` expansion that would\n   *   otherwise statically import it.\n   *\n   * Unset / empty → behaviour is byte-identical to a build without this knob:\n   * no files are skipped.\n   *\n   * Mirrors `Config::bundle` in crates/zfb/src/config.rs.\n   */\n  exclude?: string[];\n\n  /**\n   * Explicit esbuild `main-fields` list for the `--platform=neutral` page/SSR\n   * pass. Under `neutral` esbuild's main-fields list is EMPTY by default, so a\n   * dep resolved purely via `package.json` `main`/`module` (no `exports` map)\n   * is rejected (\"The \"main\" field here was ignored. Main fields must be\n   * configured explicitly when using the neutral platform.\"). Set e.g.\n   * `[\"main\", \"module\"]` to let such CJS-main-only deps resolve (#676 —\n   * `msw` → `path-to-regexp@6`). Applies to every framework; unset/empty →\n   * byte-identical to a build without the knob (the React-only `main,module`\n   * shim still applies).\n   *\n   * Mirrors `BundleConfig::main_fields` in `crates/zfb/src/config.rs`.\n   */\n  mainFields?: string[];\n\n  /**\n   * Bare specifiers to mark external in the `--platform=neutral` page/SSR\n   * pass, so esbuild leaves them unbundled instead of resolving them (the\n   * other #676 escape hatch — externalize a CJS-only dep rather than\n   * resolving it). Appended to the framework-provided externals. Unset/empty\n   * → no extra externals.\n   *\n   * Mirrors `BundleConfig::external` in `crates/zfb/src/config.rs`.\n   */\n  external?: string[];\n\n  /**\n   * Additional esbuild loaders keyed by file extension (for example\n   * `{ \".txt\": \"text\" }`). Only inline loaders are supported: `file` and\n   * `copy` are intentionally excluded because they emit sibling assets the\n   * client bundlers do not publish. `.css`, `.module.css`, `.mdx`, and `.md`\n   * are reserved by zfb and rejected during config validation.\n   */\n  loaders?: Record<string, \"text\" | \"json\" | \"base64\" | \"dataurl\" | \"binary\" | \"empty\">;\n\n  /**\n   * Operator-authored esbuild define substitutions. Values are raw esbuild\n   * expressions; string values must be pre-quoted JSON (for example\n   * `{ __APP_NAME__: '\"my-app\"' }`). The mode-owned keys\n   * `import.meta.env.PROD`, `import.meta.env.DEV`, and\n   * `process.env.NODE_ENV` are reserved and rejected at config-load time.\n   */\n  define?: Record<string, string>;\n};\n\n/**\n * One plugin entry in `zfb.config.ts`.\n *\n * `name` MUST be a module reference that Node's resolver can locate from\n * the project root. The zfb config loader\n * (`crates/zfb-config-loader/js/config-loader.mjs`) resolves it to an\n * absolute module specifier and the build / dev plugin host loads it via\n * dynamic `import()`:\n *\n * - `\"./plugins/my-plugin.mjs\"` / `\"../shared/plugin.mjs\"` —\n *   path-relative to the project root (the dir containing `zfb.config.ts`).\n * - `\"/abs/path/to/plugin.mjs\"` — absolute filesystem path.\n * - `\"@takazudo/zfb-plugin-search\"` / `\"my-plugin\"` — npm bare specifier\n *   resolved against the project's `node_modules`.\n *\n * Inline-function hooks are NOT supported; the plugin module's default\n * export must be a [`ZfbPlugin`] (see `@takazudo/zfb/plugins`).\n *\n * `options` is passed verbatim to the plugin's hook contexts; treat\n * the schema as plugin-specific.\n */\nexport type PluginConfig = {\n  name: string;\n  options?: Record<string, unknown>;\n};\n\nexport type ZfbConfig = {\n  /** Output directory for built assets. Default: `dist`. */\n  outDir?: string;\n  /** Public/static directory copied verbatim. Default: `public`. */\n  publicDir?: string;\n  /** Optional dev/preview server bind host. */\n  host?: string;\n  /** Optional dev/preview server port. */\n  port?: number;\n  /**\n   * Host header values the dev/preview server accepts when bound to a\n   * non-localhost interface (`--host 0.0.0.0`, the bare `--host` LAN\n   * shortcut, or `host` above) — the DNS-rebinding guard, mirroring\n   * Vite's `server.allowedHosts`.\n   *\n   * Defaults: only consulted for non-loopback binds — the default\n   * `localhost` bind skips validation entirely. `localhost`, the\n   * explicitly bound host, and any IP-literal Host — `127.0.0.1`,\n   * `[::1]`, the LAN URLs the startup banner prints — are always\n   * allowed (DNS rebinding needs a DNS name, so raw IPs are safe;\n   * Vite parity); requests with any other Host get a 403.\n   *\n   * Matching rules (the request Host's port is stripped first and\n   * comparison is case-insensitive):\n   *\n   * - `\"example.com\"` — matches exactly that host.\n   * - `\".example.com\"` (leading dot) — matches `example.com` and every\n   *   subdomain (`api.example.com`).\n   * - IPv6 entries may be written with or without brackets\n   *   (`\"[::1]\"` / `\"::1\"`).\n   *\n   * Mirrors `Config::allowed_hosts` in `crates/zfb/src/config.rs`.\n   */\n  allowedHosts?: string[];\n  /** JSX framework runtime. Default: `preact`. */\n  framework?: Framework;\n  /** Content collections. Mirrors the JSON form one-for-one. */\n  collections?: CollectionDef[];\n  /** Tailwind options; absent = defaults. */\n  tailwind?: TailwindConfig;\n  /**\n   * Prefetch options. When `disabled: true`, the build emits a meta tag\n   * that the runtime's prefetch-core module reads at init time to skip\n   * all prefetch wiring. Mirrors `Config::prefetch` in\n   * `crates/zfb/src/config.rs`.\n   */\n  prefetch?: PrefetchConfig;\n  /**\n   * Minify production HTML output from `zfb build`. Default: `false`.\n   *\n   * The implementation is Rust-only and does not spawn a Node.js minifier\n   * subprocess. The first version is intentionally conservative: rendered\n   * `.html` pages are candidates, source `.html` passthrough pages remain\n   * verbatim, and non-HTML outputs are skipped.\n   *\n   * Mirrors `Config::minify_html` in `crates/zfb/src/config.rs`.\n   */\n  minifyHtml?: boolean;\n  /**\n   * Raise broken-link diagnostics to errors during `zfb build`, failing the\n   * build (exit non-zero) instead of merely warning. Default: `false`.\n   *\n   * This is the effective boolean the CLI's `--strict-broken` /\n   * `--no-strict-broken` tri-state resolves against. Precedence: explicit\n   * CLI flag > this config field > default `false`.\n   *\n   * Force-enable semantics: if `markdown.features.linkValidation` is absent\n   * entirely, enabling this force-enables link validation with its\n   * defaults — a strict flag that silently did nothing on a bare project\n   * would be a footgun.\n   *\n   * Scope: the `linkValidation` mechanism only. The separate\n   * `resolveMarkdownLinks.onBrokenLinks` mechanism keeps its own knob and is\n   * not affected by this field.\n   *\n   * Build-only: it does not affect `zfb dev`.\n   *\n   * Mirrors `Config::strict_broken_links` in `crates/zfb/src/config.rs`.\n   */\n  strictBrokenLinks?: boolean;\n  /**\n   * Fail `zfb build` (exit non-zero) when a content-collection `.md`/`.mdx`\n   * entry falls back to `<pre data-zfb-content-fallback>` because its\n   * compiled JSX does not parse. Default: `false`.\n   *\n   * This is the effective boolean the CLI's `--strict-content-bridge` /\n   * `--no-strict-content-bridge` tri-state resolves against. Precedence:\n   * explicit CLI flag > this config field > default `false`.\n   *\n   * Unlike `strictBrokenLinks`, there is no adjacent feature to\n   * force-enable: the content-bridge gate always runs for every compiled\n   * collection entry.\n   *\n   * Build-only: it does not affect `zfb dev` — dev keeps warning and\n   * serving the fallback shape.\n   *\n   * Mirrors `Config::strict_content_bridge` in `crates/zfb/src/config.rs`.\n   */\n  strictContentBridge?: boolean;\n  /**\n   * Bundler options. `bundle.exclude` lists project-relative globs of\n   * source files to keep out of the esbuild graph (e.g.\n   * `[\"components/*.stories.tsx\"]`) — see {@link BundleConfig.exclude} for\n   * why this is needed. Unset → byte-identical to a build without the knob.\n   * Mirrors `Config::bundle` in `crates/zfb/src/config.rs`.\n   */\n  bundle?: BundleConfig;\n  /** User-supplied plugins. */\n  plugins?: PluginConfig[];\n  /**\n   * Deploy-target adapter package name. Omit (or `\"none\"`) for a pure\n   * static build — any route exporting `prerender = false` is then a\n   * hard build error. A package name like\n   * `\"@takazudo/zfb-adapter-cloudflare\"` selects the matching adapter,\n   * and `zfb build` invokes that package's bin to wrap the SSR bundle\n   * into a deploy-ready entry (e.g. `dist/_worker.js` for Cloudflare\n   * Workers Static Assets, Pages-compatible).\n   *\n   * Mirrors `Config::adapter` in crates/zfb/src/config.rs.\n   */\n  adapter?: string;\n  /**\n   * Strip `.md` / `.mdx` from internal `<a href>` paths during MDX\n   * compilation, and append a trailing `/` so the resulting URL shape\n   * converges with the rest of the site (mirrors the JS engine's\n   * `rehypeStripMdExtension`). Default: `false`.\n   *\n   * Enable this when content authors hand-write `[label](other.md)`\n   * style references that should resolve to the rendered route URL\n   * (e.g. `other/`) instead of a literal file path. Built dist and\n   * `pnpm dev` honour the same flag, so previews match shipped output.\n   *\n   * Mirrors `Config::strip_md_ext` in crates/zfb/src/config.rs.\n   */\n  stripMdExt?: boolean;\n\n  /**\n   * Public URL prefix mounted in front of every absolute HTML asset\n   * URL the build emits — `<link rel=\"stylesheet\">`, `<script type=\"module\">`,\n   * and any other `/assets/...`-prefixed reference rewritten by the\n   * production asset pipeline.\n   *\n   * Use this when the site is deployed under a sub-path (e.g.\n   * `https://example.com/pj/zudo-doc/`) instead of the domain root.\n   * With `base: \"/pj/zudo-doc/\"` the dist HTML emits\n   * `<link rel=\"stylesheet\" href=\"/pj/zudo-doc/assets/styles-<hash>.css\">`\n   * instead of the unprefixed `/assets/styles-<hash>.css`.\n   *\n   * Accepted shapes (all normalised to a single canonical form\n   * internally):\n   *\n   * - omitted / `undefined` / `\"\"` / `\"/\"` — no prefix; behaviour is\n   *   byte-identical to the pre-`base` build (root-mounted site).\n   * - leading-and-trailing-slash path like `\"/pj/zudo-doc/\"` — prefix\n   *   that path onto every asset URL.\n   * - absolute URL like `\"https://cdn.example.com/\"` — emit absolute\n   *   URLs (CDN-hosted assets).\n   *\n   * Inputs missing a leading or trailing `/` are normalised at config-\n   * load time (paths) or asset-emit time (URL prefixes); callers do\n   * not have to pre-trim.\n   *\n   * Mirrors `Config::base` in crates/zfb/src/config.rs.\n   */\n  base?: string;\n\n  /**\n   * Canonical origin URL for the site (e.g. `\"https://example.com\"`).\n   *\n   * When set, the bundler emits `globalThis.__zfb.site = <value>` in\n   * `entry.mjs` so layouts can build canonical `<link>` tags,\n   * OpenGraph `og:url` meta, sitemap absolute hrefs, and hreflang\n   * `<link rel=\"alternate\">` from a single config-level source of truth.\n   *\n   * **Distinct from `base`**: `base` is a sub-path mount prefix used\n   * for asset URLs (e.g. `\"/pj/my-site/\"`). `site` is the full\n   * canonical origin (scheme + host, no path) used to construct\n   * absolute page URLs for SEO/social metadata. Both may be set\n   * simultaneously.\n   *\n   * Accepted shape: an absolute HTTP or HTTPS URL. Relative URLs,\n   * non-HTTP(S) schemes, and empty strings are rejected at config-load\n   * time. Trailing slash normalisation is the consumer's responsibility.\n   *\n   * When absent, `globalThis.__zfb.site` is not emitted — the build\n   * output is byte-for-byte identical to builds without this field.\n   *\n   * Mirrors `Config::site` in crates/zfb/src/config.rs.\n   */\n  site?: string;\n\n  /**\n   * Markdown link resolver (port of `remarkResolveMarkdownLinks`).\n   *\n   * When `enabled: true`, the build appends `ResolveLinksPlugin` to the\n   * mdast pipeline so author-written `[label](./other.mdx)` links are\n   * rewritten to the corresponding rendered route URL — bypassing the\n   * file→directory transformation that breaks relative paths in dist\n   * HTML when `foo.mdx` becomes `foo/index.html`. Extensionless\n   * (`./other`) and directory-style (`other/`) targets resolve too,\n   * probing `{name}.mdx`, `{name}.md`, `{name}/index.mdx`,\n   * `{name}/index.md` in that order. Relative targets resolve from the\n   * source file's directory; for a directory-style link written from a\n   * non-index page against its rendered URL — which sits one directory\n   * deeper, e.g. `../sibling/` from `section/article.mdx` — a URL-space\n   * fallback retries the probe from the page's route directory when\n   * every file-space candidate misses.\n   *\n   * Two ways to specify the source dirs:\n   *\n   * - **Single dir (legacy):** set `docsDir` and the build assumes the\n   *   `/docs/` route prefix. Convenient for single-locale projects.\n   * - **Multi dir (`dirs` non-empty):** explicit `{ dir, routePrefix }`\n   *   entries — required for any project with locale mirrors (e.g.\n   *   `docs/` AND `docs-ja/`) so each dir maps to its own route prefix\n   *   (`/docs/` vs `/ja/docs/`). When `dirs` is non-empty, `docsDir`\n   *   is ignored.\n   *\n   * Mirrors `Config::resolve_markdown_links` in crates/zfb/src/config.rs.\n   */\n  resolveMarkdownLinks?: ResolveMarkdownLinksConfig;\n\n  /**\n   * Whether the basePath rewriter should append a trailing `/` to\n   * extensionless absolute hrefs (`<a href=\"/docs/foo\">` becomes\n   * `<a href=\"/pj/zudo-doc/docs/foo/\">` when `base = \"/pj/zudo-doc/\"`\n   * and this is `true`).\n   *\n   * Off by default — preserves byte-for-byte parity with the\n   * pre-`trailingSlash` build for projects that haven't opted in.\n   * Enable when the deploy target serves canonical URLs with trailing\n   * slashes (Cloudflare Pages with `trailingSlash: always`, Netlify\n   * pretty URLs, etc.) so the dist HTML doesn't ship non-canonical\n   * hrefs that 301-redirect on every click.\n   *\n   * Only the trailing slash for extensionless hrefs is affected.\n   * Hrefs that already end in `/`, that have a file extension\n   * (`.png`, `.pdf`, …), or that opt out via `data-no-base` pass\n   * through unchanged.\n   *\n   * Mirrors `Config::trailing_slash` in crates/zfb/src/config.rs.\n   */\n  trailingSlash?: boolean;\n\n  /**\n   * Markdown / MDX parsing options. Currently the only knob exposed is\n   * [`gfm`](MarkdownConfig.gfm), which toggles GFM constructs\n   * (strikethrough, table, autolink-literal, task-list-item,\n   * footnote-definition) on or off.\n   *\n   * Mirrors `Config::markdown` in crates/zfb/src/config.rs.\n   */\n  markdown?: MarkdownConfig;\n\n  /**\n   * Extra absolute filesystem paths watched by the dev server in\n   * addition to the project-root tree.\n   *\n   * Use this when project content reads from outside the project root\n   * (a sibling knowledge-base repo, a shared filesystem directory, a\n   * `file:` dep that ships content alongside code, etc.) and you want\n   * `zfb dev` to live-reload when those external files change.\n   *\n   * Semantics:\n   *\n   * - Each entry MUST be an absolute path. Relative paths are\n   *   rejected at config-load time with a clear error message.\n   * - Paths are canonicalised when the watcher boots; events match\n   *   the canonical form.\n   * - A path that does NOT exist at boot is skipped with a warning;\n   *   the watcher does NOT re-watch the path if it appears later.\n   *   Restart `zfb dev` after creating the path.\n   * - Each entry is watched recursively.\n   * - Events from outside the project root bypass fine-grained graph\n   *   classification and may trigger a broader rebuild than equivalent\n   *   in-tree edits.\n   *\n   * **Security note:** opt-in only — do NOT point this at unbounded\n   * directories like `$HOME` or `/`. On Linux the recursive watcher\n   * registers every subdirectory and can hit the inotify\n   * `max_user_watches` ceiling on large trees.\n   *\n   * Mirrors `Config::extra_watch_paths` in crates/zfb/src/config.rs.\n   */\n  extraWatchPaths?: string[];\n\n  /**\n   * Whether `zfb build` writes the post-build route manifest to disk\n   * at `<outDir>/__zfb/routes.json` (#347).\n   *\n   * The on-disk file mirrors the in-memory `ctx.routes` shape that the\n   * plugin API hands to `postBuild` hooks — same fields, same\n   * url-sorted order — so any consumer script wired into `pnpm build`\n   * can read the manifest without writing a zfb plugin. The plugin\n   * `ctx.routes` and the on-disk `routes.json` are two access shapes\n   * over the same data, not two contracts.\n   *\n   * Default: emit (`undefined` is treated as `true`). Set `false` to\n   * skip the write — useful for projects that strip everything but\n   * shipped assets out of `dist/` before deploy.\n   *\n   * Mirrors `Config::emit_routes_manifest` in crates/zfb/src/config.rs.\n   */\n  emitRoutesManifest?: boolean;\n\n  /**\n   * Syntect code-highlight options; absent = default theme\n   * (`base16-ocean.dark`) and inline color mode. See\n   * {@link CodeHighlightConfig} for accepted theme names, custom-theme\n   * loading, and the class-emission mode (Highlight Tokens epic).\n   *\n   * Mirrors `Config::code_highlight` in crates/zfb/src/config.rs.\n   */\n  codeHighlight?: CodeHighlightConfig;\n\n  /**\n   * Maximum seconds a single plugin lifecycle hook (preBuild, postBuild,\n   * setup, etc.) may run before the build fails with a diagnostic error\n   * and the plugin host is force-killed.\n   *\n   * Absent falls through to the `ZFB_PLUGIN_HOOK_TIMEOUT` env var, then\n   * the 120s built-in default. Set this when your plugins do long but\n   * bounded work (e.g. large sitemap generation) and you want a tighter\n   * or more explicit budget.\n   *\n   * Mirrors `Config::plugin_hook_timeout_secs` in crates/zfb/src/config.rs.\n   */\n  pluginHookTimeoutSecs?: number;\n\n  /**\n   * Whether `copy_public_dir` copies `public/` under the `base`\n   * sub-path segment (`true`, default) or flat to the `dist/` root\n   * (`false`).\n   *\n   * - **`true` (default):** files land at\n   *   `<outDir>/<base-segment>/<rel>`, matching the base-prefixed URLs\n   *   that `withBase()` emits in the rendered HTML. Use this for\n   *   projects served directly at their configured sub-path.\n   * - **`false`:** files land flat at `<outDir>/<rel>` regardless of\n   *   `base`. Use this when the deploy pipeline relocates the entire\n   *   `dist/` tree into the base segment itself (e.g.\n   *   `cp -a dist/. deploy-root/pj/site/`), so putting the files under\n   *   `<outDir>/<base>/...` would result in a double-nested path.\n   *\n   * **Note on `zfb preview`:** with `false`, base-prefixed public-asset\n   * URLs 404 under `zfb preview` because the flat copy lives at the\n   * dist root and `zfb preview` does not simulate deploy-side\n   * relocation. This is a known trade-off of the flat-copy deploy\n   * scheme.\n   *\n   * Mirrors `Config::copy_public_with_base` in crates/zfb/src/config.rs.\n   */\n  copyPublicWithBase?: boolean;\n\n  /**\n   * Opt into `notify`'s poll-based watch backend for the dev server's\n   * watchers instead of the OS-native backend (FSEvents on macOS,\n   * inotify on Linux, ...).\n   *\n   * Use this as a fallback when the native backend is unavailable or\n   * unreliable on the host (network-mounted project directories, some\n   * CI/sandboxed containers) — the poll backend re-scans the watched\n   * roots on an interval instead of relying on OS filesystem-change\n   * notifications.\n   *\n   * Default: `false` (native backend). See\n   * {@link watchPollIntervalMs} for the re-scan cadence.\n   *\n   * Mirrors `Config::watch_poll_fallback` in crates/zfb/src/config.rs.\n   */\n  watchPollFallback?: boolean;\n\n  /**\n   * Re-scan interval, in milliseconds, for the poll watch backend. Only\n   * takes effect when {@link watchPollFallback} is `true`.\n   *\n   * Validated at config-load time: must be between `50` and `10000`\n   * (inclusive) — values outside that range are rejected (too low\n   * busy-loops the poll thread; too high makes hot-reload feel broken).\n   * A value below `100` is accepted but logs a warning (elevated\n   * re-scan CPU cost on large trees). Setting this WITHOUT\n   * `watchPollFallback: true` is accepted and dormant, with a logged\n   * warning rather than an error — a preset may pre-stage the interval\n   * ahead of a project enabling the fallback itself.\n   *\n   * Absent falls through to the built-in 500ms default, applied by the\n   * consuming command.\n   *\n   * Mirrors `Config::watch_poll_interval_ms` in crates/zfb/src/config.rs.\n   */\n  watchPollIntervalMs?: number;\n\n  /**\n   * Project output mode. Drives the V8-mode decision the build engine\n   * makes right after the no-SSR-without-adapter precondition check\n   * (sub-task 4.1b / issue #373):\n   *\n   * - `\"static\"` — declare a pure-static (SSG-only) project. Errors at\n   *   build start if any route exports `prerender = false`, pointing\n   *   at the offending route. Use this on projects that must never\n   *   accidentally pick up an SSR route as a result of a copy-paste.\n   * - `\"hybrid\"` — declare a project that may host SSR routes. V8-on\n   *   regardless of detection, even when no `prerender = false` route\n   *   currently exists. Useful for projects that will add SSR routes\n   *   later and want a stable build topology in the meantime.\n   * - `\"auto\"` (default) — detection-driven. Non-empty `prerender =\n   *   false` route set => V8-on; empty => V8-off.\n   *\n   * Today's load-bearing role is the `\"static\"` precondition check.\n   * The V8-off branch does NOT skip V8 host startup on the shipping\n   * `zfb` binary — SSG still needs V8 to render pages. The flag exists\n   * as infrastructure for the future shipping path (Tauri sidecar /\n   * standalone SSR server). See the\n   * [Build engine docs](https://github.com/Takazudo/zudo-front-builder/blob/main/docs/src/content/docs/architecture/build-engine.mdx)\n   * for the gate decision table.\n   *\n   * Mirrors `Config::output` in crates/zfb/src/config.rs.\n   */\n  output?: OutputMode;\n\n  /**\n   * Config presets to merge before validation (#1196).\n   *\n   * Each preset is a partial `ZfbConfig`-shaped object. The merge pass runs\n   * BEFORE field validation and folds preset contributions using additive\n   * semantics:\n   *\n   * - **Array fields** (`plugins`, `collections`, `extraWatchPaths`,\n   *   `allowedHosts`): preset values are prepended so the main config's\n   *   entries retain their relative position after the preset's.\n   * - **Scalar / optional fields**: a preset value fills in only when the\n   *   main config leaves the field at its default — the main config is\n   *   authoritative; presets act as defaults.\n   *\n   * Nested `presets` inside a preset are NOT recursively expanded.\n   *\n   * Mirrors `Config::presets` in crates/zfb/src/config.rs.\n   */\n  presets?: Partial<ZfbConfig>[];\n};\n\n/**\n * Project output mode.\n *\n * - `\"static\"` — pure-static (SSG-only); errors on detected SSR routes.\n * - `\"hybrid\"` — may host SSR routes; V8-on regardless of detection.\n * - `\"auto\"` — detection-driven; the default.\n *\n * Mirrors `OutputMode` in crates/zfb/src/config.rs.\n */\nexport type OutputMode = \"static\" | \"hybrid\" | \"auto\";\n\n/**\n * Syntect code-highlight options.\n *\n * Unknown theme names are rejected at build start with a clear error\n * rather than silently falling back.\n *\n * **Single-theme mode** (the default): set `theme` to a syntect theme name,\n * or omit it to use the default (`\"base16-ocean.dark\"`). Tokens are colored\n * with inline `color:`.\n *\n * **Dual-theme mode**: set both `themeLight` and `themeDark`. Tokens are\n * colored with CSS custom properties (`--shiki-light` / `--shiki-dark`),\n * and the consumer applies a `light-dark()` rule to pick the active color.\n * The `<pre>` element carries `class=\"syntect-dual\"` and\n * `--shiki-light-bg` / `--shiki-dark-bg` in its `style` attribute.\n *\n * `theme` and the dual pair are mutually exclusive. Setting only one of\n * `themeLight` / `themeDark` is an error.\n *\n * All theme names are **SYNTECT** built-in or user-loaded names (e.g.\n * `\"base16-ocean.light\"`, `\"base16-ocean.dark\"`, `\"InspiredGitHub\"`,\n * `\"Solarized (dark)\"`), NOT Shiki names like `\"dracula\"`.\n *\n * **Class mode** (Highlight Tokens epic, zfb#1528): set `mode: \"class\"`.\n * Each token gets a semantic role class instead of an inline color, so\n * highlight colors become re-themeable CSS design tokens. Mutually\n * exclusive with `theme` / `themeLight` / `themeDark` / `themesDir` —\n * themes don't affect class emission, so setting both is a build error.\n *\n * Mirrors `CodeHighlightConfig` in crates/zfb/src/config.rs.\n */\nexport type CodeHighlightConfig = {\n  /**\n   * Syntect built-in or user-loaded theme name. When absent the\n   * pipeline defaults to `\"base16-ocean.dark\"`.\n   *\n   * Mutually exclusive with {@link themeLight} / {@link themeDark}.\n   * Must be a SYNTECT theme name (e.g. `\"InspiredGitHub\"`), NOT a Shiki name.\n   */\n  theme?: string;\n  /**\n   * Path to a directory of `.tmTheme` files, relative to the project\n   * root. Every `.tmTheme` file in the directory is loaded and becomes\n   * available by its declared `name` via {@link theme}, {@link themeLight},\n   * or {@link themeDark}. When absent only syntect's bundled themes are\n   * available.\n   *\n   * The path must be relative and must not escape the project root via\n   * `..`. A missing directory is reported as an error at build start.\n   *\n   * Applies to both single-theme and dual-theme mode.\n   */\n  themesDir?: string;\n  /**\n   * Light-mode syntect theme name for dual-theme highlighting.\n   *\n   * Must be set together with {@link themeDark} — setting only one of\n   * the two is a build error. When both are set, tokens are colored with\n   * CSS custom properties (`--shiki-light` / `--shiki-dark`) instead of\n   * inline `color:`. Mutually exclusive with {@link theme}.\n   *\n   * Must be a SYNTECT theme name (e.g. `\"base16-ocean.light\"`),\n   * NOT a Shiki name like `\"dracula\"`.\n   */\n  themeLight?: string;\n  /**\n   * Dark-mode syntect theme name for dual-theme highlighting.\n   *\n   * Must be set together with {@link themeLight} — setting only one of\n   * the two is a build error. Mutually exclusive with {@link theme}.\n   *\n   * Must be a SYNTECT theme name (e.g. `\"base16-ocean.dark\"`),\n   * NOT a Shiki name like `\"dracula\"`.\n   */\n  themeDark?: string;\n  /**\n   * Output mode for fenced-code highlighting (Highlight Tokens epic,\n   * zfb#1528). `\"inline\"` (default) bakes per-token colors into\n   * `style=\"color:#rrggbb\"` (or the dual `--shiki-*` custom properties).\n   * `\"class\"` emits a semantic role class per token instead, so colors\n   * become re-themeable CSS design tokens rather than baked-in HTML.\n   *\n   * Mutually exclusive with {@link theme} / {@link themeLight} /\n   * {@link themeDark} / {@link themesDir} — themes don't affect class\n   * emission, so setting both is rejected rather than silently ignoring\n   * the theme.\n   */\n  mode?: CodeHighlightMode;\n  /**\n   * Class-name prefix for class-mode role classes (e.g. the default\n   * `\"hi-\"` yields `hi-kw`, `hi-str`, ...). Must match\n   * `/^[A-Za-z][A-Za-z0-9_-]*$/`. Only meaningful when {@link mode} is\n   * `\"class\"`. Default: `\"hi-\"`.\n   */\n  classPrefix?: string;\n  /**\n   * Per-role class overrides for class mode, e.g.\n   * `{ keyword: \"text-violet-600 dark:text-violet-400\" }` to map a role\n   * onto Tailwind utilities instead of the default `{classPrefix}{role}`\n   * class. Keys must be one of the 18 fixed role names (see\n   * {@link CodeHighlightRole}); a value may hold multiple\n   * space-separated classes and must not contain the bare token `\"line\"`\n   * (collides with the code-enrichment line wrapper class). Absent uses\n   * `{classPrefix}{role}` for every role.\n   *\n   * Setting this while `tailwind.enabled` is `false` (the authored-CSS\n   * path) is allowed but emits a build warning — no Tailwind safelist can\n   * be generated on that path, so the mapped utilities must already exist\n   * in your own CSS.\n   */\n  roleClasses?: Partial<Record<CodeHighlightRole, string>>;\n  /**\n   * Whether to inject the built-in `--zfb-hi-*` token stylesheet\n   * (`zfb-hi.css`) into the combined `styles.css` output. Only meaningful\n   * in class mode. Default: `true`.\n   */\n  defaultStylesheet?: boolean;\n};\n\n/**\n * `codeHighlight.mode` — see {@link CodeHighlightConfig.mode}.\n *\n * Mirrors `CodeHighlightMode` in crates/zfb/src/config.rs.\n */\nexport type CodeHighlightMode = \"inline\" | \"class\";\n\n/**\n * The fixed 18-role semantic taxonomy for class-mode syntax highlighting\n * (Highlight Tokens epic, zfb#1528) — valid {@link CodeHighlightConfig.roleClasses}\n * keys.\n *\n * Mirrors `CODE_HIGHLIGHT_ROLES` in crates/zfb/src/config.rs.\n */\nexport type CodeHighlightRole =\n  | \"escape\"\n  | \"operator\"\n  | \"comment\"\n  | \"string\"\n  | \"number\"\n  | \"constant\"\n  | \"keyword\"\n  | \"function\"\n  | \"type\"\n  | \"namespace\"\n  | \"property\"\n  | \"variable\"\n  | \"tag\"\n  | \"attribute\"\n  | \"punctuation\"\n  | \"inserted\"\n  | \"deleted\"\n  | \"heading\";\n\n/**\n * Table-of-contents options. Wire via `markdown.toc` in `zfb.config.ts`.\n *\n * When present, a TOC `<ul>/<li>` list is inserted as the next sibling\n * of the first heading whose text matches `heading` (case-insensitive).\n * Each `<a href=\"#id\">` links to the deduplicated `id` that\n * `HeadingLinksPlugin` placed on the corresponding heading.\n *\n * Mirrors `TocConfig` in `crates/zfb-content/src/plugins/toc.rs`.\n */\nexport type TocConfig = {\n  /**\n   * Heading text that triggers TOC insertion. Matched\n   * case-insensitively after whitespace trimming. Default: `\"TOC\"`.\n   */\n  heading?: string;\n\n  /**\n   * Number of heading levels to include starting from `<h2>`.\n   *\n   * - `1` — h2 only\n   * - `2` (default) — h2 + h3\n   * - `3` — h2, h3, h4\n   * - …up to `5` (h2 through h6)\n   */\n  maxDepth?: number;\n};\n\n/**\n * Markdown / MDX parsing options.\n *\n * See [`ZfbConfig.markdown`] for the embed point. Fields: [`gfm`],\n * [`toc`], [`externalLinks`], [`cjkFriendly`], and [`features`].\n * Future markdown knobs would also live here.\n *\n * See the \"Markdown Features\" docs category for the per-feature option\n * reference once individual features are ported.\n *\n * Mirrors `MarkdownConfig` in crates/zfb/src/config.rs.\n */\nexport type MarkdownConfig = {\n  /**\n   * Enable GFM constructs.\n   *\n   * Accepts three shapes:\n   *\n   * - `true` — turn every GFM construct ON (strikethrough, table,\n   *   autolink-literal, task-list-item, footnote-definition).\n   * - `false` — turn every GFM construct OFF.\n   * - partial object — set individual fields explicitly; fields you\n   *   omit fall back to the conservative-default values described\n   *   below.\n   *\n   * When `markdown` itself is omitted entirely, the conservative\n   * default applies: `strikethrough: true`, `table: true`,\n   * `autolinkLiteral: true`, task lists and footnotes off. Those three\n   * are the constructs GFM-accustomed authors expect without config;\n   * task lists and footnotes change document structure, so they stay\n   * opt-in. Projects that want the full GFM surface should opt in with\n   * `gfm: true`.\n   */\n  gfm?: GfmFlag;\n\n  /**\n   * Table-of-contents options. When present, a `<ul>/<li>` list is\n   * inserted after the first heading whose text matches `heading`\n   * (default `\"TOC\"`, case-insensitive). Each link points to the\n   * deduplicated `id` that `HeadingLinksPlugin` placed on the heading.\n   *\n   * Omitting this field entirely leaves the build byte-for-byte identical\n   * to the pre-TOC build. See [`TocConfig`] for the available options.\n   *\n   * Mirrors `MarkdownConfig::toc` in crates/zfb/src/config.rs.\n   */\n  toc?: TocConfig;\n  /**\n   * External-link rewriter. When set, every `<a>` whose href is\n   * classified as external receives the configured `target` and `rel`\n   * attributes.\n   *\n   * An href is external when it is an absolute HTTP/HTTPS URL AND its\n   * origin differs from the top-level `site` URL (if `site` is\n   * configured). When `site` is absent, any absolute HTTP/HTTPS URL is\n   * treated as external.\n   *\n   * `mailto:`, `tel:`, and other non-HTTP(S) schemes are always left\n   * unchanged. Relative URLs (`/internal/`, `./file.mdx`, `#anchor`) are\n   * always internal.\n   *\n   * Omitting this field keeps the output byte-for-byte identical to the\n   * pre-feature behaviour.\n   *\n   * Mirrors `ExternalLinksConfig` in crates/zfb/src/config.rs.\n   */\n  externalLinks?: ExternalLinksConfig;\n\n  /**\n   * Enable CJK-friendly markdown handling.\n   *\n   * Governs two post-parse fixups that adapt CommonMark/GFM rules to CJK\n   * text:\n   *\n   * 1. **Emphasis/strong flanking** (`CjkFriendlyPlugin`). CommonMark's\n   *    left-/right-flanking delimiter-run rules treat CJK characters as\n   *    non-whitespace non-punctuation, which causes `**foo**` adjacent to\n   *    CJK text (e.g. `**テスト。**テスト`) to render as literal stars\n   *    instead of `<strong>`.\n   * 2. **Bare-URL autolink boundary** (`CjkAutolinkBoundaryPlugin`,\n   *    zfb#1105). The GFM autolink-literal path grammar terminates only on\n   *    ASCII whitespace, so a bare URL flush against CJK text\n   *    (`詳細はhttps://example.com参照`) swallows the trailing CJK run into\n   *    the `href`. This fixup terminates the link at the first CJK\n   *    character. Only active when `gfm.autolinkLiteral` is also on.\n   *\n   * - **absent / `true` (default):** CJK-friendly handling is on.\n   *   Preserves today's behaviour — existing CJK-content sites are\n   *   unaffected.\n   * - **`false`:** opt-out. Neither plugin is added to the pipeline;\n   *   emphasis markers and bare-URL autolinks adjacent to CJK characters\n   *   follow base CommonMark/GFM rules. Rarely the right choice; provided\n   *   as an escape hatch for projects that need strict CommonMark/GFM\n   *   output.\n   *\n   * **GFM strikethrough** (`~~foo~~`) at CJK boundaries is unaffected\n   * by this toggle — it is handled by markdown-rs's GFM tokeniser, not\n   * by these plugins, and works correctly in both modes.\n   *\n   * Mirrors `MarkdownConfig::cjk_friendly` in crates/zfb/src/config.rs.\n   */\n  cjkFriendly?: boolean;\n\n  /**\n   * Convert every soft line break (a single `\\n` inside a paragraph) into\n   * `<br>` (remark-breaks parity).\n   *\n   * - **absent / `false` (default):** soft line breaks follow standard\n   *   CommonMark behaviour — collapsed into a single space.\n   * - **`true`:** every `\\n` inside a paragraph becomes `<br>`. Use this\n   *   when your content relies on newline→`<br>` fidelity (e.g. product\n   *   descriptions, lyrics, or other newline-sensitive prose).\n   *\n   * Mirrors `MarkdownConfig::hard_breaks` in crates/zfb/src/config.rs.\n   */\n  hardBreaks?: boolean;\n\n  /**\n   * Per-feature markdown pipeline toggles.\n   *\n   * Each field is a [`FeatureToggle`] (`true` / `false` / options object)\n   * or a feature-specific config type (for features that require extra\n   * parameters). Absent / `undefined` means all features are disabled,\n   * preserving the behaviour of the pre-features build byte-for-byte.\n   *\n   * Unknown keys are rejected at deserialization time by the Rust loader\n   * so a typo in `zfb.config.ts` surfaces as a clear error.\n   *\n   * Mirrors `MarkdownFeaturesConfig` in crates/zfb/src/config.rs.\n   */\n  features?: MarkdownFeaturesConfig;\n};\n\n/**\n * Per-feature toggle: `boolean` shorthand or an options object.\n *\n * `true` enables the feature with defaults; `false` (or absent) disables it.\n * The object form carries per-feature options (fields vary by feature and\n * are filled in by each feature's port sub-issue — stubs today).\n *\n * Mirrors `FeatureToggle` in crates/zfb/src/config.rs.\n */\nexport type FeatureToggle = boolean | FeatureOptions;\n\n/**\n * Empty options object for features that accept `{ ... }` but have no\n * user-facing knobs yet. Fields are filled in by each feature's port\n * sub-issue; this stub satisfies the schema shape requirement.\n *\n * Mirrors `FeatureOptions` in crates/zfb/src/config.rs.\n */\nexport type FeatureOptions = Record<string, never>;\n\n/**\n * Options for the `codeEnrichment` feature.\n *\n * All flags default to `true` when the feature is enabled with\n * `codeEnrichment: {}` or when a field is absent.\n *\n * Mirrors `CodeEnrichmentConfig` in `crates/zfb-md-ast/src/features_config.rs`.\n */\nexport type CodeEnrichmentConfig = {\n  /**\n   * Enable diff-marker processing for markers such as `// [!code ++]`\n   * and `// [!code --]`. Default: `true`.\n   */\n  diffMarkers?: boolean;\n  /**\n   * Enable line-highlight processing for fence ranges such as `{1,3-5}`.\n   * Default: `true`.\n   */\n  lineHighlight?: boolean;\n  /**\n   * Enable visible-text word emphasis for slash-delimited fence metadata\n   * such as `/answer/`. Default: `true`.\n   */\n  wordHighlight?: boolean;\n};\n\n/**\n * Options for the `tocExport` feature.\n *\n * Controls which headings are included in the exported `toc` JSON.\n * `maxDepth` is the **absolute** heading depth (2–6):\n *   - `2` → h2 only\n *   - `3` (default) → h2 + h3\n *\n * This differs from `headingMarkerToc.maxDepth`, which counts levels\n * starting from h2. The two features are independent.\n *\n * Mirrors `TocExportConfig` in crates/zfb-md-ast/src/features_config.rs.\n */\nexport type TocExportConfig = {\n  /** Maximum heading depth to include (absolute, 2–6). Default: 3. */\n  maxDepth?: number;\n};\n\n/**\n * Options for the `imageDimensions` feature.\n *\n * Auto-detects and injects `width`/`height` on local `<img>` elements. Raster\n * formats are probed header-only; SVGs are read from their markup\n * (`width`/`height`/`viewBox`).\n *\n * Mirrors `ImageDimensionsConfig` in crates/zfb-md-ast/src/features_config.rs.\n */\nexport type ImageDimensionsConfig = {\n  /**\n   * When `true` (the default), `http://` and `https://` image sources are\n   * silently skipped and not probed for dimensions. Set to `false` only for\n   * testing or unusual setups — remote images require network access at build\n   * time and slow the pipeline.\n   */\n  skipRemote?: boolean;\n};\n\n/**\n * Options for the `linkValidation` feature.\n *\n * Validates internal `[text](file.md#anchor)` and `[text](#anchor)` links at\n * build time. External URLs (`http://`, `https://`, `mailto:`) are always\n * skipped — network validation is out of scope.\n *\n * Mirrors `LinkValidationConfig` in `crates/zfb-md-ast/src/features_config.rs`.\n */\nexport type LinkValidationConfig = {\n  /**\n   * When `true`, broken links are reported as errors (build can fail).\n   * Default: `false` (warn-only).\n   */\n  failOnBroken?: boolean;\n};\n\n/**\n * Options for the `transclude` feature.\n *\n * Enables `:::include{file=\"./path.md\"}` directives that inline another\n * file's parsed mdast at the include site.\n *\n * Mirrors `TranscludeConfig` in crates/zfb-md-ast/src/features_config.rs.\n */\nexport type TranscludeConfig = {\n  /**\n   * Maximum transclusion depth (chain length A→B→C→…).\n   *\n   * A depth of `1` allows only direct includes (the included file itself\n   * cannot include further files). Default: `5`. A cycle (A→B→A) is\n   * always detected regardless of `maxDepth` and treated as an error.\n   */\n  maxDepth?: number;\n};\n\n/**\n * Options for the `readingTime` feature.\n *\n * Mirrors `ReadingTimeOptions` in crates/zfb-md-ast/src/features_config.rs.\n */\nexport type ReadingTimeConfig = {\n  /** Words-per-minute rate for the reading-time estimate. Default: 200. */\n  wpm?: number;\n};\n\n/**\n * `readingTime` feature value: either a `boolean` shorthand or a\n * {@link ReadingTimeConfig} options object.\n *\n * Mirrors `ReadingTimeFeature` in crates/zfb-md-ast/src/features_config.rs.\n */\nexport type ReadingTimeFeature = boolean | ReadingTimeConfig;\n\n/**\n * Per-feature markdown pipeline configuration.\n *\n * All fields are optional; absent = feature disabled, behaviour unchanged\n * from the pre-features build. Unknown keys are rejected at deserialization\n * time by the Rust loader so a typo surfaces as a clear error.\n *\n * Mirrors `MarkdownFeaturesConfig` in crates/zfb/src/config.rs.\n */\nexport type MarkdownFeaturesConfig = {\n  /** GitHub-style alert blocks (`> [!NOTE]`, `> [!WARNING]`, etc.). */\n  githubAlerts?: FeatureToggle;\n\n  /**\n   * Reading-time estimate injected into the document frontmatter.\n   * Accepts `true` / `false` shorthand or `{ wpm: N }` for a custom rate.\n   */\n  readingTime?: ReadingTimeFeature;\n\n  /** Code-block enrichment (copy button, language label, etc.). */\n  codeEnrichment?: CodeEnrichmentConfig;\n\n  /** Grouped code blocks rendered as tabs. */\n  codeTabs?: FeatureToggle;\n\n  /** Ruby annotation support (`{base}^{ruby}` syntax). */\n  ruby?: FeatureToggle;\n\n  /** Export the page TOC as structured data (e.g. for sidebar rendering). */\n  tocExport?: TocExportConfig;\n\n  /** Auto-detect and inject `width`/`height` on `<img>` elements. */\n  imageDimensions?: ImageDimensionsConfig;\n\n  /**\n   * Validate internal links (file-relative paths and anchor fragments) at\n   * build time. External URLs are always skipped — network validation is\n   * out of scope.\n   */\n  linkValidation?: LinkValidationConfig;\n\n  /**\n   * Transclusion of other markdown/MDX files via\n   * `:::include{file=\"./path.md\"}` — NOT the Obsidian `[[path]]` wikilink\n   * syntax.\n   */\n  transclude?: TranscludeConfig;\n\n  /**\n   * Generic `:::name` → component map. You supply the components; no defaults\n   * are registered. Keys are directive names (e.g. `\"foo\"`), values are\n   * {@link DirectiveSpec} (bare component name string or options object).\n   *\n   * Mirrors `directives` in `MarkdownFeaturesConfig` in crates/zfb/src/config.rs.\n   */\n  directives?: Record<string, DirectiveSpec>;\n\n  /** Mermaid diagram rendering. */\n  mermaid?: FeatureToggle;\n\n  /**\n   * Inline heading-marker TOC. Accepts either a `boolean` shorthand\n   * (`true` = enable with defaults, `false` = disable) or a full\n   * {@link TocConfig} options object — same union shape as the Rust\n   * `HeadingMarkerTocFeature` enum.\n   */\n  headingMarkerToc?: HeadingMarkerTocFeature;\n\n  /**\n   * Heading-ID strategy for the always-on `HeadingLinks` plugin.\n   * Absent → `\"flat\"` (the long-standing github-slugger scheme).\n   * `{ strategy: \"hierarchical\" }` opts into ancestor-prefixed anchor\n   * IDs (`## Foo` / `### Moo` / `#### Mew` → `foo`, `foo-moo`,\n   * `foo-moo-mew`) — see {@link HeadingIdsConfig}.\n   */\n  headingIds?: HeadingIdsConfig;\n};\n\n/**\n * Options for the `headingIds` entry in `markdown.features`.\n *\n * Configures the always-on `HeadingLinks` plugin rather than toggling an\n * opt-in feature. Note: switching to `\"hierarchical\"` is anchor-breaking\n * for existing deep links to nested headings.\n *\n * Mirrors `HeadingIdsConfig` in crates/zfb-md-ast/src/features_config.rs.\n */\nexport type HeadingIdsConfig = {\n  /**\n   * `\"flat\"` (default): github-slugger slugs with a per-document dedup\n   * counter shared across h2–h6 (`overview`, `overview-1`, …).\n   * `\"hierarchical\"`: each heading's slug is prefixed with its ancestor\n   * chain and deduped on the full path — anchors become reconstructible\n   * from the heading outline.\n   */\n  strategy?: \"flat\" | \"hierarchical\";\n};\n\n/**\n * `headingMarkerToc` feature value: either a `boolean` shorthand or a\n * full {@link TocConfig} options object.\n *\n * Mirrors `HeadingMarkerTocFeature` in crates/zfb-md-ast/src/features_config.rs.\n */\nexport type HeadingMarkerTocFeature = boolean | TocConfig;\n\n/**\n * Spec for one user-defined directive: either a bare component name string\n * or a full {@link DirectiveFullSpec} options object.\n *\n * Mirrors `DirectiveSpec` in crates/zfb-md-ast/src/features_config.rs.\n */\nexport type DirectiveSpec = string | DirectiveFullSpec;\n\n/**\n * Full options object for one user-defined directive.\n *\n * Mirrors `DirectiveFullSpec` in crates/zfb-md-ast/src/features_config.rs.\n */\nexport type DirectiveFullSpec = {\n  /** JSX component identifier (e.g. `\"Spoiler\"`, `\"Kbd\"`). */\n  component: string;\n  /** Container/leaf/text shape. Defaults to `\"container\"` when absent. */\n  kind?: \"container\" | \"leaf\" | \"text\";\n  /** Whether the bracketed `[label]` becomes a `title` attribute. Defaults to `true`. */\n  titleFromLabel?: boolean;\n};\n\n/**\n * Options for the external-link rewriter (port of `rehype-external-links`).\n *\n * All fields are optional; omitting a field applies the documented default.\n *\n * Mirrors `ExternalLinksConfig` in crates/zfb/src/config.rs.\n */\nexport type ExternalLinksConfig = {\n  /**\n   * `rel` tokens applied to external links.\n   *\n   * Default: `[\"noopener\", \"noreferrer\"]`.\n   *\n   * Tokens are deduplicated (case-insensitive) and merged with any\n   * existing `rel` attribute on the `<a>` element — existing tokens\n   * appear first.\n   */\n  rel?: string[];\n  /**\n   * `target` value for external links.\n   *\n   * Default: `\"_blank\"`.\n   */\n  target?: string;\n};\n\n/**\n * Either the shorthand boolean form (`true` = all GFM constructs on,\n * `false` = all off) or a partial object that toggles individual\n * constructs.\n *\n * Mirrors `GfmFlag` in crates/zfb/src/config.rs.\n */\nexport type GfmFlag = boolean | GfmConstructs;\n\n/**\n * Per-construct opt-in / opt-out for GFM. Every field is optional;\n * omitted fields fall back to the conservative default\n * (`strikethrough: true`, `table: true`, `autolinkLiteral: true`,\n * others `false`).\n *\n * Mirrors `GfmConstructs` in crates/zfb/src/config.rs.\n */\nexport type GfmConstructs = {\n  /** GFM strikethrough (`~~text~~` → `<del>text</del>`). */\n  strikethrough?: boolean;\n  /** GFM pipe-style tables. */\n  table?: boolean;\n  /**\n   * GFM autolink literal — bare URLs like `https://example.com` become\n   * clickable links without `<…>` brackets.\n   */\n  autolinkLiteral?: boolean;\n  /** GFM task list items (`- [x]` / `- [ ]`). */\n  taskListItem?: boolean;\n  /** GFM footnote definitions (`[^ref]: …`). */\n  footnoteDefinition?: boolean;\n};\n\n/**\n * What to do when a `.md`/`.mdx` link cannot be resolved.\n *\n * Mirrors `OnBrokenLinks` in crates/zfb/src/config.rs.\n */\nexport type OnBrokenLinks = \"warn\" | \"error\" | \"ignore\";\n\n/**\n * Config for the markdown link resolver. See\n * [`ZfbConfig.resolveMarkdownLinks`] for the design rationale.\n */\nexport type ResolveMarkdownLinksConfig = {\n  /** Whether to enable link resolution. Default: `false`. */\n  enabled?: boolean;\n\n  /**\n   * Legacy single-dir field. Used only when [`dirs`] is empty. When\n   * non-empty, scanned against the hard-coded `/docs/` route prefix.\n   */\n  docsDir?: string;\n\n  /**\n   * Explicit per-dir source map. Each entry is one collection (e.g.\n   * EN docs at `src/content/docs/` → `/docs/`, JA docs at\n   * `src/content/docs-ja/` → `/ja/docs/`). Takes precedence over\n   * [`docsDir`] when non-empty.\n   */\n  dirs?: ResolveMarkdownLinksDir[];\n\n  /** What to do with unresolved `.md`/`.mdx` links. Default: `\"warn\"`. */\n  onBrokenLinks?: OnBrokenLinks;\n};\n\n/** One source-dir entry for [`ResolveMarkdownLinksConfig.dirs`]. */\nexport type ResolveMarkdownLinksDir = {\n  /**\n   * Directory (relative to project root) whose `.md`/`.mdx` files are\n   * scanned. Must be relative and must not escape the root via `..`.\n   */\n  dir: string;\n\n  /**\n   * Route prefix prepended to each file's slug. Include leading and\n   * trailing slashes (e.g. `\"/docs/\"` or `\"/ja/docs/\"`).\n   */\n  routePrefix: string;\n};\n\n/**\n * Identity helper: returns the supplied config as-is, but typed against\n * [`ZfbConfig`]. Use as the default export of `zfb.config.ts` so editors\n * surface field-level types and typos surface at compile time.\n */\nexport function defineConfig(config: ZfbConfig): ZfbConfig {\n  return config;\n}\n\n/**\n * Preset authoring helper: stamps each object entry in `config.plugins`\n * with `source_package: sourcePackage` so the Rust loader can attribute\n * plugin contributions back to the preset package that provided them.\n *\n * - Only plain-object plugin entries are stamped; non-object entries pass\n *   through unchanged (defensive — the current schema requires objects,\n *   but this guard keeps the helper safe if the schema is ever relaxed).\n * - An entry that ALREADY carries a `source_package` is left untouched, so a\n *   preset composing another `definePreset`-returned preset (by spreading its\n *   `plugins`) keeps the inner preset's provenance instead of clobbering it\n *   with the outer package name (the spread below lets the existing marker win).\n * - When `config.plugins` is absent, the config is returned as-is.\n * - All other fields of `config` pass through unchanged.\n *\n * The key `source_package` (snake_case) mirrors the Rust `PluginConfig`\n * serde field added in T4. `PluginConfig` has no `#[serde(rename_all)]`\n * so the serde key is the field name verbatim — do NOT use camelCase.\n *\n * SYNC REQUIREMENT: keep this implementation behaviourally identical to\n * the stub in crates/zfb-config-loader/js/zfb-config-stub.mjs, which is\n * injected at config-eval time when the user's project does not have the\n * zfb npm package installed locally.\n */\nexport function definePreset(\n  sourcePackage: string,\n  config: Partial<ZfbConfig>,\n): Partial<ZfbConfig> {\n  if (!config.plugins) {\n    return config;\n  }\n  return {\n    ...config,\n    plugins: config.plugins.map((plugin) => {\n      if (plugin !== null && typeof plugin === \"object\" && !Array.isArray(plugin)) {\n        // Default first, then spread the plugin so an existing `source_package`\n        // (from a composed inner preset) wins over the outer package name.\n        return { source_package: sourcePackage, ...plugin };\n      }\n      return plugin;\n    }),\n  };\n}\n"]}
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,iEAAiE;AACjE,EAAE;AACF,kEAAkE;AAClE,qEAAqE;AACrE,uEAAuE;AACvE,oEAAoE;AACpE,+BAA+B;AAC/B,EAAE;AACF,yEAAyE;AACzE,uEAAuE;AACvE,uEAAuE;AACvE,kEAAkE;AAClE,EAAE;AACF,uEAAuE;AACvE,uEAAuE;AA8zCvE;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,MAAiB;IAC5C,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,YAAY,CAC1B,aAAqB,EACrB,MAA0B;IAE1B,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACpB,OAAO,MAAM,CAAC;IAChB,CAAC;IACD,OAAO;QACL,GAAG,MAAM;QACT,OAAO,EAAE,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE;YACrC,IAAI,MAAM,KAAK,IAAI,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;gBAC5E,wEAAwE;gBACxE,mEAAmE;gBACnE,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,GAAG,MAAM,EAAE,CAAC;YACtD,CAAC;YACD,OAAO,MAAM,CAAC;QAChB,CAAC,CAAC;KACH,CAAC;AACJ,CAAC","sourcesContent":["// `zfb/config` — TypeScript helper for the `zfb.config.ts` form.\n//\n// The zfb config loader (`crates/zfb/src/config.rs`) accepts both\n// `zfb.config.ts` and `zfb.config.json`; TS wins when both files are\n// present. JSON remains accepted for projects predating the TS loader,\n// while new projects should prefer the TS form for editor types and\n// `defineConfig` autocomplete.\n//\n// At parse time, zfb bundles the user's `zfb.config.ts` with esbuild and\n// aliases this `zfb/config` import to an internal stub that re-exports\n// `defineConfig` as the identity function — so a user project does not\n// need the `zfb` npm package installed locally just to be parsed.\n//\n// The shape mirrors the Rust `Config` struct one-for-one. Keep them in\n// sync; the `defineConfig` identity helper is the single anchor point.\n\nexport type Framework = \"preact\" | \"react\";\n\nexport type CollectionDef = {\n  /** Identifier used at the call site (e.g. `\"blog\"`). */\n  name: string;\n  /** Directory (relative to the project root) holding the entries. */\n  path: string;\n  /** Optional schema. Enforced by `zfb check`. */\n  schema?: Record<string, unknown>;\n  /**\n   * Optional include globs (Astro-style, evaluated relative to `path`).\n   * When set and non-empty, an entry is kept only if at least one\n   * pattern matches its relative path. When omitted or empty, no\n   * include-filtering happens. Patterns use the `globset` dialect\n   * (Unix-style: `*`, `**`, `?`, `[…]`).\n   */\n  include?: string[];\n  /**\n   * Optional exclude globs. When set, an entry is dropped if any\n   * pattern matches its relative path. Evaluated AFTER `include`.\n   * Together they mirror Astro's `['**\\/*.mdx', '!**\\/*.en.mdx']`\n   * convention (zfb splits the negative side into its own field).\n   */\n  exclude?: string[];\n  /**\n   * Optional suffix to strip from each kept entry's slug + module\n   * specifier. Use with multi-locale layouts where one source\n   * directory holds both `foo.mdx` (default locale) and `foo.en.mdx`\n   * (locale override) — set `idStripSuffix: \".en\"` so the EN\n   * collection's slugs round-trip as `foo` instead of `foo.en`.\n   */\n  idStripSuffix?: string;\n  /**\n   * Opt-in to a `path` that escapes the project root via `..` (e.g. a\n   * monorepo-shared content dir living outside this package). Default\n   * `false` keeps the standard project-root guard. Absolute paths and\n   * Windows drive-relative/prefix forms are rejected regardless of\n   * this flag — only `..`-relative escapes are relaxed.\n   *\n   * Security note: if this collection comes from a preset, the preset\n   * author — not the consuming project — controls `path`. Setting\n   * `allowOutsideRoot: true` on a preset-provided collection widens\n   * the project's read surface to wherever that preset points, so\n   * treat it the same as any other preset-granted filesystem access.\n   */\n  allowOutsideRoot?: boolean;\n};\n\nexport type TailwindConfig = {\n  /** Whether Tailwind is enabled. Default: `true`. */\n  enabled?: boolean;\n};\n\n/**\n * Prefetch options. Mirrors `PrefetchConfig` in `crates/zfb/src/config.rs`.\n */\nexport type PrefetchConfig = {\n  /**\n   * Disable prefetch entirely.\n   *\n   * When `true`, the bundler emits `globalThis.__zfb.prefetchDisabled = true`\n   * in `entry.mjs`, and `<ClientRouter />` renders\n   * `<meta name=\"zfb-prefetch-disabled\" content=\"true\">` in `<head>`.\n   * The sibling prefetch-core module reads that meta tag at `init()` time\n   * and short-circuits — no prefetch wiring runs.\n   *\n   * The flag is site-wide and static — set once at bundle-emit time,\n   * never recomputed per-page. Default: `false`.\n   */\n  disabled?: boolean;\n};\n\n/**\n * Bundler options. Mirrors `BundleConfig` in `crates/zfb/src/config.rs`.\n */\nexport type BundleConfig = {\n  /**\n   * Project-relative glob patterns (gitignore-style) for source files\n   * the bundler must NOT pull into the esbuild graph.\n   *\n   * Why this exists: an eager `import.meta.glob('components/**\\/*.stories.tsx',\n   * { eager: true })` expands to a static import of every matched file. If a\n   * matched file imports a CJS-only package whose `package.json` resolves only\n   * via `main`/`module` or a `require`-only `exports` condition (e.g.\n   * `msw` → `path-to-regexp@6`), esbuild — invoked with `--platform=neutral`\n   * for the worker bundle — rejects it with \"Could not resolve … Main fields\n   * must be configured explicitly when using the neutral platform.\" Listing the\n   * offending file here keeps the migration build green.\n   *\n   * Each pattern is matched against the file's path RELATIVE TO THE PROJECT\n   * ROOT, in POSIX form (e.g. `components/Foo.stories.tsx` or\n   * `components/**\\/*.stories.tsx`). A matched file is:\n   *\n   * - never copied/symlinked into the bundler's shadow tree, and\n   * - dropped from any eager `import.meta.glob(...)` expansion that would\n   *   otherwise statically import it.\n   *\n   * Unset / empty → behaviour is byte-identical to a build without this knob:\n   * no files are skipped.\n   *\n   * Mirrors `Config::bundle` in crates/zfb/src/config.rs.\n   */\n  exclude?: string[];\n\n  /**\n   * Explicit esbuild `main-fields` list for the `--platform=neutral` page/SSR\n   * pass. Under `neutral` esbuild's main-fields list is EMPTY by default, so a\n   * dep resolved purely via `package.json` `main`/`module` (no `exports` map)\n   * is rejected (\"The \"main\" field here was ignored. Main fields must be\n   * configured explicitly when using the neutral platform.\"). Set e.g.\n   * `[\"main\", \"module\"]` to let such CJS-main-only deps resolve (#676 —\n   * `msw` → `path-to-regexp@6`). Applies to every framework; unset/empty →\n   * byte-identical to a build without the knob (the React-only `main,module`\n   * shim still applies).\n   *\n   * Mirrors `BundleConfig::main_fields` in `crates/zfb/src/config.rs`.\n   */\n  mainFields?: string[];\n\n  /**\n   * Bare specifiers to mark external in the `--platform=neutral` page/SSR\n   * pass, so esbuild leaves them unbundled instead of resolving them (the\n   * other #676 escape hatch — externalize a CJS-only dep rather than\n   * resolving it). Appended to the framework-provided externals. Unset/empty\n   * → no extra externals.\n   *\n   * Mirrors `BundleConfig::external` in `crates/zfb/src/config.rs`.\n   */\n  external?: string[];\n\n  /**\n   * Additional esbuild loaders keyed by file extension (for example\n   * `{ \".txt\": \"text\" }`). Only inline loaders are supported: `file` and\n   * `copy` are intentionally excluded because they emit sibling assets the\n   * client bundlers do not publish. `.css`, `.module.css`, `.mdx`, and `.md`\n   * are reserved by zfb and rejected during config validation.\n   */\n  loaders?: Record<string, \"text\" | \"json\" | \"base64\" | \"dataurl\" | \"binary\" | \"empty\">;\n\n  /**\n   * Operator-authored esbuild define substitutions. Values are raw esbuild\n   * expressions; string values must be pre-quoted JSON (for example\n   * `{ __APP_NAME__: '\"my-app\"' }`). The mode-owned keys\n   * `import.meta.env.PROD`, `import.meta.env.DEV`, and\n   * `process.env.NODE_ENV` are reserved and rejected at config-load time.\n   */\n  define?: Record<string, string>;\n};\n\n/**\n * One plugin entry in `zfb.config.ts`.\n *\n * `name` MUST be a module reference that Node's resolver can locate from\n * the project root. The zfb config loader\n * (`crates/zfb-config-loader/js/config-loader.mjs`) resolves it to an\n * absolute module specifier and the build / dev plugin host loads it via\n * dynamic `import()`:\n *\n * - `\"./plugins/my-plugin.mjs\"` / `\"../shared/plugin.mjs\"` —\n *   path-relative to the project root (the dir containing `zfb.config.ts`).\n * - `\"/abs/path/to/plugin.mjs\"` — absolute filesystem path.\n * - `\"@takazudo/zfb-plugin-search\"` / `\"my-plugin\"` — npm bare specifier\n *   resolved against the project's `node_modules`.\n *\n * Inline-function hooks are NOT supported; the plugin module's default\n * export must be a [`ZfbPlugin`] (see `@takazudo/zfb/plugins`).\n *\n * `options` is passed verbatim to the plugin's hook contexts; treat\n * the schema as plugin-specific.\n */\nexport type PluginConfig = {\n  name: string;\n  options?: Record<string, unknown>;\n};\n\nexport type ZfbConfig = {\n  /** Output directory for built assets. Default: `dist`. */\n  outDir?: string;\n  /** Public/static directory copied verbatim. Default: `public`. */\n  publicDir?: string;\n  /** Optional dev/preview server bind host. */\n  host?: string;\n  /** Optional dev/preview server port. */\n  port?: number;\n  /**\n   * Host header values the dev/preview server accepts when bound to a\n   * non-localhost interface (`--host 0.0.0.0`, the bare `--host` LAN\n   * shortcut, or `host` above) — the DNS-rebinding guard, mirroring\n   * Vite's `server.allowedHosts`.\n   *\n   * Defaults: only consulted for non-loopback binds — the default\n   * `localhost` bind skips validation entirely. `localhost`, the\n   * explicitly bound host, and any IP-literal Host — `127.0.0.1`,\n   * `[::1]`, the LAN URLs the startup banner prints — are always\n   * allowed (DNS rebinding needs a DNS name, so raw IPs are safe;\n   * Vite parity); requests with any other Host get a 403.\n   *\n   * Matching rules (the request Host's port is stripped first and\n   * comparison is case-insensitive):\n   *\n   * - `\"example.com\"` — matches exactly that host.\n   * - `\".example.com\"` (leading dot) — matches `example.com` and every\n   *   subdomain (`api.example.com`).\n   * - IPv6 entries may be written with or without brackets\n   *   (`\"[::1]\"` / `\"::1\"`).\n   *\n   * Mirrors `Config::allowed_hosts` in `crates/zfb/src/config.rs`.\n   */\n  allowedHosts?: string[];\n  /** JSX framework runtime. Default: `preact`. */\n  framework?: Framework;\n  /** Content collections. Mirrors the JSON form one-for-one. */\n  collections?: CollectionDef[];\n  /** Tailwind options; absent = defaults. */\n  tailwind?: TailwindConfig;\n  /**\n   * Prefetch options. When `disabled: true`, the build emits a meta tag\n   * that the runtime's prefetch-core module reads at init time to skip\n   * all prefetch wiring. Mirrors `Config::prefetch` in\n   * `crates/zfb/src/config.rs`.\n   */\n  prefetch?: PrefetchConfig;\n  /**\n   * Minify production HTML output from `zfb build`. Default: `false`.\n   *\n   * The implementation is Rust-only and does not spawn a Node.js minifier\n   * subprocess. The first version is intentionally conservative: rendered\n   * `.html` pages are candidates, source `.html` passthrough pages remain\n   * verbatim, and non-HTML outputs are skipped.\n   *\n   * Mirrors `Config::minify_html` in `crates/zfb/src/config.rs`.\n   */\n  minifyHtml?: boolean;\n  /**\n   * Raise broken-link diagnostics to errors during `zfb build`, failing the\n   * build (exit non-zero) instead of merely warning. Default: `false`.\n   *\n   * This is the effective boolean the CLI's `--strict-broken` /\n   * `--no-strict-broken` tri-state resolves against. Precedence: explicit\n   * CLI flag > this config field > default `false`.\n   *\n   * Force-enable semantics: if `markdown.features.linkValidation` is absent\n   * entirely, enabling this force-enables link validation with its\n   * defaults — a strict flag that silently did nothing on a bare project\n   * would be a footgun.\n   *\n   * Scope: the `linkValidation` mechanism only. The separate\n   * `resolveMarkdownLinks.onBrokenLinks` mechanism keeps its own knob and is\n   * not affected by this field.\n   *\n   * Build-only: it does not affect `zfb dev`.\n   *\n   * Mirrors `Config::strict_broken_links` in `crates/zfb/src/config.rs`.\n   */\n  strictBrokenLinks?: boolean;\n  /**\n   * Fail `zfb build` (exit non-zero) when a content-collection `.md`/`.mdx`\n   * entry falls back to `<pre data-zfb-content-fallback>` because its\n   * compiled JSX does not parse. Default: `false`.\n   *\n   * This is the effective boolean the CLI's `--strict-content-bridge` /\n   * `--no-strict-content-bridge` tri-state resolves against. Precedence:\n   * explicit CLI flag > this config field > default `false`.\n   *\n   * Unlike `strictBrokenLinks`, there is no adjacent feature to\n   * force-enable: the content-bridge gate always runs for every compiled\n   * collection entry.\n   *\n   * Build-only: it does not affect `zfb dev` — dev keeps warning and\n   * serving the fallback shape.\n   *\n   * Mirrors `Config::strict_content_bridge` in `crates/zfb/src/config.rs`.\n   */\n  strictContentBridge?: boolean;\n  /**\n   * Whether `zfb build` writes a JSON render artifact for every\n   * markdown/MDX-backed HTML route whose rendered page contains exactly\n   * one top-level content region — the content-region HTML as shipped,\n   * compiler-allocated headings with slugs, a contract version, and a\n   * raw-source digest (Render Artifact Export epic #2421). The extraction\n   * pass and artifact writer are Rust-side\n   * (`crate::commands::render_artifact::export_render_artifacts`),\n   * running between the link-base rewrite and HTML minification. See the\n   * [Render Artifacts docs](https://github.com/Takazudo/zudo-front-builder/blob/main/docs/src/content/docs/concepts/render-artifacts.mdx)\n   * for the full JSON contract.\n   *\n   * This is the effective boolean the CLI's `--emit-render-artifacts` /\n   * `--no-emit-render-artifacts` tri-state resolves against. Precedence:\n   * explicit CLI flag > this config field > default `false`.\n   *\n   * Default: `false` (explicit opt-in), unlike `emitRoutesManifest`'s\n   * default-on posture — the writer instruments every rendered region\n   * with sentinel markers before stripping them back out, and the epic\n   * keeps that opt-in until the confirm sub-issue proves flag-off output\n   * stays byte-identical.\n   *\n   * Build-only: it does not affect `zfb dev`.\n   *\n   * Mirrors `Config::emit_render_artifacts` in `crates/zfb/src/config.rs`.\n   */\n  emitRenderArtifacts?: boolean;\n  /**\n   * Bundler options. `bundle.exclude` lists project-relative globs of\n   * source files to keep out of the esbuild graph (e.g.\n   * `[\"components/*.stories.tsx\"]`) — see {@link BundleConfig.exclude} for\n   * why this is needed. Unset → byte-identical to a build without the knob.\n   * Mirrors `Config::bundle` in `crates/zfb/src/config.rs`.\n   */\n  bundle?: BundleConfig;\n  /** User-supplied plugins. */\n  plugins?: PluginConfig[];\n  /**\n   * Deploy-target adapter package name. Omit (or `\"none\"`) for a pure\n   * static build — any route exporting `prerender = false` is then a\n   * hard build error. A package name like\n   * `\"@takazudo/zfb-adapter-cloudflare\"` selects the matching adapter,\n   * and `zfb build` invokes that package's bin to wrap the SSR bundle\n   * into a deploy-ready entry (e.g. `dist/_worker.js` for Cloudflare\n   * Workers Static Assets, Pages-compatible).\n   *\n   * Mirrors `Config::adapter` in crates/zfb/src/config.rs.\n   */\n  adapter?: string;\n  /**\n   * Strip `.md` / `.mdx` from internal `<a href>` paths during MDX\n   * compilation, and append a trailing `/` so the resulting URL shape\n   * converges with the rest of the site (mirrors the JS engine's\n   * `rehypeStripMdExtension`). Default: `false`.\n   *\n   * Enable this when content authors hand-write `[label](other.md)`\n   * style references that should resolve to the rendered route URL\n   * (e.g. `other/`) instead of a literal file path. Built dist and\n   * `pnpm dev` honour the same flag, so previews match shipped output.\n   *\n   * Mirrors `Config::strip_md_ext` in crates/zfb/src/config.rs.\n   */\n  stripMdExt?: boolean;\n\n  /**\n   * Public URL prefix mounted in front of every absolute HTML asset\n   * URL the build emits — `<link rel=\"stylesheet\">`, `<script type=\"module\">`,\n   * and any other `/assets/...`-prefixed reference rewritten by the\n   * production asset pipeline.\n   *\n   * Use this when the site is deployed under a sub-path (e.g.\n   * `https://example.com/pj/zudo-doc/`) instead of the domain root.\n   * With `base: \"/pj/zudo-doc/\"` the dist HTML emits\n   * `<link rel=\"stylesheet\" href=\"/pj/zudo-doc/assets/styles-<hash>.css\">`\n   * instead of the unprefixed `/assets/styles-<hash>.css`.\n   *\n   * Accepted shapes (all normalised to a single canonical form\n   * internally):\n   *\n   * - omitted / `undefined` / `\"\"` / `\"/\"` — no prefix; behaviour is\n   *   byte-identical to the pre-`base` build (root-mounted site).\n   * - leading-and-trailing-slash path like `\"/pj/zudo-doc/\"` — prefix\n   *   that path onto every asset URL.\n   * - absolute URL like `\"https://cdn.example.com/\"` — emit absolute\n   *   URLs (CDN-hosted assets).\n   *\n   * Inputs missing a leading or trailing `/` are normalised at config-\n   * load time (paths) or asset-emit time (URL prefixes); callers do\n   * not have to pre-trim.\n   *\n   * Mirrors `Config::base` in crates/zfb/src/config.rs.\n   */\n  base?: string;\n\n  /**\n   * Canonical origin URL for the site (e.g. `\"https://example.com\"`).\n   *\n   * When set, the bundler emits `globalThis.__zfb.site = <value>` in\n   * `entry.mjs` so layouts can build canonical `<link>` tags,\n   * OpenGraph `og:url` meta, sitemap absolute hrefs, and hreflang\n   * `<link rel=\"alternate\">` from a single config-level source of truth.\n   *\n   * **Distinct from `base`**: `base` is a sub-path mount prefix used\n   * for asset URLs (e.g. `\"/pj/my-site/\"`). `site` is the full\n   * canonical origin (scheme + host, no path) used to construct\n   * absolute page URLs for SEO/social metadata. Both may be set\n   * simultaneously.\n   *\n   * Accepted shape: an absolute HTTP or HTTPS URL. Relative URLs,\n   * non-HTTP(S) schemes, and empty strings are rejected at config-load\n   * time. Trailing slash normalisation is the consumer's responsibility.\n   *\n   * When absent, `globalThis.__zfb.site` is not emitted — the build\n   * output is byte-for-byte identical to builds without this field.\n   *\n   * Mirrors `Config::site` in crates/zfb/src/config.rs.\n   */\n  site?: string;\n\n  /**\n   * Markdown link resolver (port of `remarkResolveMarkdownLinks`).\n   *\n   * When `enabled: true`, the build appends `ResolveLinksPlugin` to the\n   * mdast pipeline so author-written `[label](./other.mdx)` links are\n   * rewritten to the corresponding rendered route URL — bypassing the\n   * file→directory transformation that breaks relative paths in dist\n   * HTML when `foo.mdx` becomes `foo/index.html`. Extensionless\n   * (`./other`) and directory-style (`other/`) targets resolve too,\n   * probing `{name}.mdx`, `{name}.md`, `{name}/index.mdx`,\n   * `{name}/index.md` in that order. Relative targets resolve from the\n   * source file's directory; for a directory-style link written from a\n   * non-index page against its rendered URL — which sits one directory\n   * deeper, e.g. `../sibling/` from `section/article.mdx` — a URL-space\n   * fallback retries the probe from the page's route directory when\n   * every file-space candidate misses.\n   *\n   * Two ways to specify the source dirs:\n   *\n   * - **Single dir (legacy):** set `docsDir` and the build assumes the\n   *   `/docs/` route prefix. Convenient for single-locale projects.\n   * - **Multi dir (`dirs` non-empty):** explicit `{ dir, routePrefix }`\n   *   entries — required for any project with locale mirrors (e.g.\n   *   `docs/` AND `docs-ja/`) so each dir maps to its own route prefix\n   *   (`/docs/` vs `/ja/docs/`). When `dirs` is non-empty, `docsDir`\n   *   is ignored.\n   *\n   * Mirrors `Config::resolve_markdown_links` in crates/zfb/src/config.rs.\n   */\n  resolveMarkdownLinks?: ResolveMarkdownLinksConfig;\n\n  /**\n   * Whether the basePath rewriter should append a trailing `/` to\n   * extensionless absolute hrefs (`<a href=\"/docs/foo\">` becomes\n   * `<a href=\"/pj/zudo-doc/docs/foo/\">` when `base = \"/pj/zudo-doc/\"`\n   * and this is `true`).\n   *\n   * Off by default — preserves byte-for-byte parity with the\n   * pre-`trailingSlash` build for projects that haven't opted in.\n   * Enable when the deploy target serves canonical URLs with trailing\n   * slashes (Cloudflare Pages with `trailingSlash: always`, Netlify\n   * pretty URLs, etc.) so the dist HTML doesn't ship non-canonical\n   * hrefs that 301-redirect on every click.\n   *\n   * Only the trailing slash for extensionless hrefs is affected.\n   * Hrefs that already end in `/`, that have a file extension\n   * (`.png`, `.pdf`, …), or that opt out via `data-no-base` pass\n   * through unchanged.\n   *\n   * Mirrors `Config::trailing_slash` in crates/zfb/src/config.rs.\n   */\n  trailingSlash?: boolean;\n\n  /**\n   * Markdown / MDX parsing options. Currently the only knob exposed is\n   * [`gfm`](MarkdownConfig.gfm), which toggles GFM constructs\n   * (strikethrough, table, autolink-literal, task-list-item,\n   * footnote-definition) on or off.\n   *\n   * Mirrors `Config::markdown` in crates/zfb/src/config.rs.\n   */\n  markdown?: MarkdownConfig;\n\n  /**\n   * Extra absolute filesystem paths watched by the dev server in\n   * addition to the project-root tree.\n   *\n   * Use this when project content reads from outside the project root\n   * (a sibling knowledge-base repo, a shared filesystem directory, a\n   * `file:` dep that ships content alongside code, etc.) and you want\n   * `zfb dev` to live-reload when those external files change.\n   *\n   * Semantics:\n   *\n   * - Each entry MUST be an absolute path. Relative paths are\n   *   rejected at config-load time with a clear error message.\n   * - Paths are canonicalised when the watcher boots; events match\n   *   the canonical form.\n   * - A path that does NOT exist at boot is skipped with a warning;\n   *   the watcher does NOT re-watch the path if it appears later.\n   *   Restart `zfb dev` after creating the path.\n   * - Each entry is watched recursively.\n   * - Events from outside the project root bypass fine-grained graph\n   *   classification and may trigger a broader rebuild than equivalent\n   *   in-tree edits.\n   *\n   * **Security note:** opt-in only — do NOT point this at unbounded\n   * directories like `$HOME` or `/`. On Linux the recursive watcher\n   * registers every subdirectory and can hit the inotify\n   * `max_user_watches` ceiling on large trees.\n   *\n   * Mirrors `Config::extra_watch_paths` in crates/zfb/src/config.rs.\n   */\n  extraWatchPaths?: string[];\n\n  /**\n   * Whether `zfb build` writes the post-build route manifest to disk\n   * at `<outDir>/__zfb/routes.json` (#347).\n   *\n   * The on-disk file mirrors the in-memory `ctx.routes` shape that the\n   * plugin API hands to `postBuild` hooks — same fields, same\n   * url-sorted order — so any consumer script wired into `pnpm build`\n   * can read the manifest without writing a zfb plugin. The plugin\n   * `ctx.routes` and the on-disk `routes.json` are two access shapes\n   * over the same data, not two contracts.\n   *\n   * Default: emit (`undefined` is treated as `true`). Set `false` to\n   * skip the write — useful for projects that strip everything but\n   * shipped assets out of `dist/` before deploy.\n   *\n   * Mirrors `Config::emit_routes_manifest` in crates/zfb/src/config.rs.\n   */\n  emitRoutesManifest?: boolean;\n\n  /**\n   * Syntect code-highlight options; absent = default theme\n   * (`base16-ocean.dark`) and inline color mode. See\n   * {@link CodeHighlightConfig} for accepted theme names, custom-theme\n   * loading, and the class-emission mode (Highlight Tokens epic).\n   *\n   * Mirrors `Config::code_highlight` in crates/zfb/src/config.rs.\n   */\n  codeHighlight?: CodeHighlightConfig;\n\n  /**\n   * Maximum seconds a single plugin lifecycle hook (preBuild, postBuild,\n   * setup, etc.) may run before the build fails with a diagnostic error\n   * and the plugin host is force-killed.\n   *\n   * Absent falls through to the `ZFB_PLUGIN_HOOK_TIMEOUT` env var, then\n   * the 120s built-in default. Set this when your plugins do long but\n   * bounded work (e.g. large sitemap generation) and you want a tighter\n   * or more explicit budget.\n   *\n   * Mirrors `Config::plugin_hook_timeout_secs` in crates/zfb/src/config.rs.\n   */\n  pluginHookTimeoutSecs?: number;\n\n  /**\n   * Whether `copy_public_dir` copies `public/` under the `base`\n   * sub-path segment (`true`, default) or flat to the `dist/` root\n   * (`false`).\n   *\n   * - **`true` (default):** files land at\n   *   `<outDir>/<base-segment>/<rel>`, matching the base-prefixed URLs\n   *   that `withBase()` emits in the rendered HTML. Use this for\n   *   projects served directly at their configured sub-path.\n   * - **`false`:** files land flat at `<outDir>/<rel>` regardless of\n   *   `base`. Use this when the deploy pipeline relocates the entire\n   *   `dist/` tree into the base segment itself (e.g.\n   *   `cp -a dist/. deploy-root/pj/site/`), so putting the files under\n   *   `<outDir>/<base>/...` would result in a double-nested path.\n   *\n   * **Note on `zfb preview`:** with `false`, base-prefixed public-asset\n   * URLs 404 under `zfb preview` because the flat copy lives at the\n   * dist root and `zfb preview` does not simulate deploy-side\n   * relocation. This is a known trade-off of the flat-copy deploy\n   * scheme.\n   *\n   * Mirrors `Config::copy_public_with_base` in crates/zfb/src/config.rs.\n   */\n  copyPublicWithBase?: boolean;\n\n  /**\n   * Opt into `notify`'s poll-based watch backend for the dev server's\n   * watchers instead of the OS-native backend (FSEvents on macOS,\n   * inotify on Linux, ...).\n   *\n   * Use this as a fallback when the native backend is unavailable or\n   * unreliable on the host (network-mounted project directories, some\n   * CI/sandboxed containers) — the poll backend re-scans the watched\n   * roots on an interval instead of relying on OS filesystem-change\n   * notifications.\n   *\n   * Default: `false` (native backend). See\n   * {@link watchPollIntervalMs} for the re-scan cadence.\n   *\n   * Mirrors `Config::watch_poll_fallback` in crates/zfb/src/config.rs.\n   */\n  watchPollFallback?: boolean;\n\n  /**\n   * Re-scan interval, in milliseconds, for the poll watch backend. Only\n   * takes effect when {@link watchPollFallback} is `true`.\n   *\n   * Validated at config-load time: must be between `50` and `10000`\n   * (inclusive) — values outside that range are rejected (too low\n   * busy-loops the poll thread; too high makes hot-reload feel broken).\n   * A value below `100` is accepted but logs a warning (elevated\n   * re-scan CPU cost on large trees). Setting this WITHOUT\n   * `watchPollFallback: true` is accepted and dormant, with a logged\n   * warning rather than an error — a preset may pre-stage the interval\n   * ahead of a project enabling the fallback itself.\n   *\n   * Absent falls through to the built-in 500ms default, applied by the\n   * consuming command.\n   *\n   * Mirrors `Config::watch_poll_interval_ms` in crates/zfb/src/config.rs.\n   */\n  watchPollIntervalMs?: number;\n\n  /**\n   * Project output mode. Drives the V8-mode decision the build engine\n   * makes right after the no-SSR-without-adapter precondition check\n   * (sub-task 4.1b / issue #373):\n   *\n   * - `\"static\"` — declare a pure-static (SSG-only) project. Errors at\n   *   build start if any route exports `prerender = false`, pointing\n   *   at the offending route. Use this on projects that must never\n   *   accidentally pick up an SSR route as a result of a copy-paste.\n   * - `\"hybrid\"` — declare a project that may host SSR routes. V8-on\n   *   regardless of detection, even when no `prerender = false` route\n   *   currently exists. Useful for projects that will add SSR routes\n   *   later and want a stable build topology in the meantime.\n   * - `\"auto\"` (default) — detection-driven. Non-empty `prerender =\n   *   false` route set => V8-on; empty => V8-off.\n   *\n   * Today's load-bearing role is the `\"static\"` precondition check.\n   * The V8-off branch does NOT skip V8 host startup on the shipping\n   * `zfb` binary — SSG still needs V8 to render pages. The flag exists\n   * as infrastructure for the future shipping path (Tauri sidecar /\n   * standalone SSR server). See the\n   * [Build engine docs](https://github.com/Takazudo/zudo-front-builder/blob/main/docs/src/content/docs/architecture/build-engine.mdx)\n   * for the gate decision table.\n   *\n   * Mirrors `Config::output` in crates/zfb/src/config.rs.\n   */\n  output?: OutputMode;\n\n  /**\n   * Config presets to merge before validation (#1196).\n   *\n   * Each preset is a partial `ZfbConfig`-shaped object. The merge pass runs\n   * BEFORE field validation and folds preset contributions using additive\n   * semantics:\n   *\n   * - **Array fields** (`plugins`, `collections`, `extraWatchPaths`,\n   *   `allowedHosts`): preset values are prepended so the main config's\n   *   entries retain their relative position after the preset's.\n   * - **Scalar / optional fields**: a preset value fills in only when the\n   *   main config leaves the field at its default — the main config is\n   *   authoritative; presets act as defaults.\n   *\n   * Nested `presets` inside a preset are NOT recursively expanded.\n   *\n   * Mirrors `Config::presets` in crates/zfb/src/config.rs.\n   */\n  presets?: Partial<ZfbConfig>[];\n};\n\n/**\n * Project output mode.\n *\n * - `\"static\"` — pure-static (SSG-only); errors on detected SSR routes.\n * - `\"hybrid\"` — may host SSR routes; V8-on regardless of detection.\n * - `\"auto\"` — detection-driven; the default.\n *\n * Mirrors `OutputMode` in crates/zfb/src/config.rs.\n */\nexport type OutputMode = \"static\" | \"hybrid\" | \"auto\";\n\n/**\n * Syntect code-highlight options.\n *\n * Unknown theme names are rejected at build start with a clear error\n * rather than silently falling back.\n *\n * **Single-theme mode** (the default): set `theme` to a syntect theme name,\n * or omit it to use the default (`\"base16-ocean.dark\"`). Tokens are colored\n * with inline `color:`.\n *\n * **Dual-theme mode**: set both `themeLight` and `themeDark`. Tokens are\n * colored with CSS custom properties (`--shiki-light` / `--shiki-dark`),\n * and the consumer applies a `light-dark()` rule to pick the active color.\n * The `<pre>` element carries `class=\"syntect-dual\"` and\n * `--shiki-light-bg` / `--shiki-dark-bg` in its `style` attribute.\n *\n * `theme` and the dual pair are mutually exclusive. Setting only one of\n * `themeLight` / `themeDark` is an error.\n *\n * All theme names are **SYNTECT** built-in or user-loaded names (e.g.\n * `\"base16-ocean.light\"`, `\"base16-ocean.dark\"`, `\"InspiredGitHub\"`,\n * `\"Solarized (dark)\"`), NOT Shiki names like `\"dracula\"`.\n *\n * **Class mode** (Highlight Tokens epic, zfb#1528): set `mode: \"class\"`.\n * Each token gets a semantic role class instead of an inline color, so\n * highlight colors become re-themeable CSS design tokens. Mutually\n * exclusive with `theme` / `themeLight` / `themeDark` / `themesDir` —\n * themes don't affect class emission, so setting both is a build error.\n *\n * Mirrors `CodeHighlightConfig` in crates/zfb/src/config.rs.\n */\nexport type CodeHighlightConfig = {\n  /**\n   * Syntect built-in or user-loaded theme name. When absent the\n   * pipeline defaults to `\"base16-ocean.dark\"`.\n   *\n   * Mutually exclusive with {@link themeLight} / {@link themeDark}.\n   * Must be a SYNTECT theme name (e.g. `\"InspiredGitHub\"`), NOT a Shiki name.\n   */\n  theme?: string;\n  /**\n   * Path to a directory of `.tmTheme` files, relative to the project\n   * root. Every `.tmTheme` file in the directory is loaded and becomes\n   * available by its declared `name` via {@link theme}, {@link themeLight},\n   * or {@link themeDark}. When absent only syntect's bundled themes are\n   * available.\n   *\n   * The path must be relative and must not escape the project root via\n   * `..`. A missing directory is reported as an error at build start.\n   *\n   * Applies to both single-theme and dual-theme mode.\n   */\n  themesDir?: string;\n  /**\n   * Light-mode syntect theme name for dual-theme highlighting.\n   *\n   * Must be set together with {@link themeDark} — setting only one of\n   * the two is a build error. When both are set, tokens are colored with\n   * CSS custom properties (`--shiki-light` / `--shiki-dark`) instead of\n   * inline `color:`. Mutually exclusive with {@link theme}.\n   *\n   * Must be a SYNTECT theme name (e.g. `\"base16-ocean.light\"`),\n   * NOT a Shiki name like `\"dracula\"`.\n   */\n  themeLight?: string;\n  /**\n   * Dark-mode syntect theme name for dual-theme highlighting.\n   *\n   * Must be set together with {@link themeLight} — setting only one of\n   * the two is a build error. Mutually exclusive with {@link theme}.\n   *\n   * Must be a SYNTECT theme name (e.g. `\"base16-ocean.dark\"`),\n   * NOT a Shiki name like `\"dracula\"`.\n   */\n  themeDark?: string;\n  /**\n   * Output mode for fenced-code highlighting (Highlight Tokens epic,\n   * zfb#1528). `\"inline\"` (default) bakes per-token colors into\n   * `style=\"color:#rrggbb\"` (or the dual `--shiki-*` custom properties).\n   * `\"class\"` emits a semantic role class per token instead, so colors\n   * become re-themeable CSS design tokens rather than baked-in HTML.\n   *\n   * Mutually exclusive with {@link theme} / {@link themeLight} /\n   * {@link themeDark} / {@link themesDir} — themes don't affect class\n   * emission, so setting both is rejected rather than silently ignoring\n   * the theme.\n   */\n  mode?: CodeHighlightMode;\n  /**\n   * Class-name prefix for class-mode role classes (e.g. the default\n   * `\"hi-\"` yields `hi-kw`, `hi-str`, ...). Must match\n   * `/^[A-Za-z][A-Za-z0-9_-]*$/`. Only meaningful when {@link mode} is\n   * `\"class\"`. Default: `\"hi-\"`.\n   */\n  classPrefix?: string;\n  /**\n   * Per-role class overrides for class mode, e.g.\n   * `{ keyword: \"text-violet-600 dark:text-violet-400\" }` to map a role\n   * onto Tailwind utilities instead of the default `{classPrefix}{role}`\n   * class. Keys must be one of the 18 fixed role names (see\n   * {@link CodeHighlightRole}); a value may hold multiple\n   * space-separated classes and must not contain the bare token `\"line\"`\n   * (collides with the code-enrichment line wrapper class). Absent uses\n   * `{classPrefix}{role}` for every role.\n   *\n   * Setting this while `tailwind.enabled` is `false` (the authored-CSS\n   * path) is allowed but emits a build warning — no Tailwind safelist can\n   * be generated on that path, so the mapped utilities must already exist\n   * in your own CSS.\n   */\n  roleClasses?: Partial<Record<CodeHighlightRole, string>>;\n  /**\n   * Whether to inject the built-in `--zfb-hi-*` token stylesheet\n   * (`zfb-hi.css`) into the combined `styles.css` output. Only meaningful\n   * in class mode. Default: `true`.\n   */\n  defaultStylesheet?: boolean;\n};\n\n/**\n * `codeHighlight.mode` — see {@link CodeHighlightConfig.mode}.\n *\n * Mirrors `CodeHighlightMode` in crates/zfb/src/config.rs.\n */\nexport type CodeHighlightMode = \"inline\" | \"class\";\n\n/**\n * The fixed 18-role semantic taxonomy for class-mode syntax highlighting\n * (Highlight Tokens epic, zfb#1528) — valid {@link CodeHighlightConfig.roleClasses}\n * keys.\n *\n * Mirrors `CODE_HIGHLIGHT_ROLES` in crates/zfb/src/config.rs.\n */\nexport type CodeHighlightRole =\n  | \"escape\"\n  | \"operator\"\n  | \"comment\"\n  | \"string\"\n  | \"number\"\n  | \"constant\"\n  | \"keyword\"\n  | \"function\"\n  | \"type\"\n  | \"namespace\"\n  | \"property\"\n  | \"variable\"\n  | \"tag\"\n  | \"attribute\"\n  | \"punctuation\"\n  | \"inserted\"\n  | \"deleted\"\n  | \"heading\";\n\n/**\n * Table-of-contents options. Wire via `markdown.toc` in `zfb.config.ts`.\n *\n * When present, a TOC `<ul>/<li>` list is inserted as the next sibling\n * of the first heading whose text matches `heading` (case-insensitive).\n * Each `<a href=\"#id\">` links to the deduplicated `id` that\n * `HeadingLinksPlugin` placed on the corresponding heading.\n *\n * Mirrors `TocConfig` in `crates/zfb-content/src/plugins/toc.rs`.\n */\nexport type TocConfig = {\n  /**\n   * Heading text that triggers TOC insertion. Matched\n   * case-insensitively after whitespace trimming. Default: `\"TOC\"`.\n   */\n  heading?: string;\n\n  /**\n   * Number of heading levels to include starting from `<h2>`.\n   *\n   * - `1` — h2 only\n   * - `2` (default) — h2 + h3\n   * - `3` — h2, h3, h4\n   * - …up to `5` (h2 through h6)\n   */\n  maxDepth?: number;\n};\n\n/**\n * Markdown / MDX parsing options.\n *\n * See [`ZfbConfig.markdown`] for the embed point. Fields: [`gfm`],\n * [`toc`], [`externalLinks`], [`cjkFriendly`], and [`features`].\n * Future markdown knobs would also live here.\n *\n * See the \"Markdown Features\" docs category for the per-feature option\n * reference once individual features are ported.\n *\n * Mirrors `MarkdownConfig` in crates/zfb/src/config.rs.\n */\nexport type MarkdownConfig = {\n  /**\n   * Enable GFM constructs.\n   *\n   * Accepts three shapes:\n   *\n   * - `true` — turn every GFM construct ON (strikethrough, table,\n   *   autolink-literal, task-list-item, footnote-definition).\n   * - `false` — turn every GFM construct OFF.\n   * - partial object — set individual fields explicitly; fields you\n   *   omit fall back to the conservative-default values described\n   *   below.\n   *\n   * When `markdown` itself is omitted entirely, the conservative\n   * default applies: `strikethrough: true`, `table: true`,\n   * `autolinkLiteral: true`, task lists and footnotes off. Those three\n   * are the constructs GFM-accustomed authors expect without config;\n   * task lists and footnotes change document structure, so they stay\n   * opt-in. Projects that want the full GFM surface should opt in with\n   * `gfm: true`.\n   */\n  gfm?: GfmFlag;\n\n  /**\n   * Table-of-contents options. When present, a `<ul>/<li>` list is\n   * inserted after the first heading whose text matches `heading`\n   * (default `\"TOC\"`, case-insensitive). Each link points to the\n   * deduplicated `id` that `HeadingLinksPlugin` placed on the heading.\n   *\n   * Omitting this field entirely leaves the build byte-for-byte identical\n   * to the pre-TOC build. See [`TocConfig`] for the available options.\n   *\n   * Mirrors `MarkdownConfig::toc` in crates/zfb/src/config.rs.\n   */\n  toc?: TocConfig;\n  /**\n   * External-link rewriter. When set, every `<a>` whose href is\n   * classified as external receives the configured `target` and `rel`\n   * attributes.\n   *\n   * An href is external when it is an absolute HTTP/HTTPS URL AND its\n   * origin differs from the top-level `site` URL (if `site` is\n   * configured). When `site` is absent, any absolute HTTP/HTTPS URL is\n   * treated as external.\n   *\n   * `mailto:`, `tel:`, and other non-HTTP(S) schemes are always left\n   * unchanged. Relative URLs (`/internal/`, `./file.mdx`, `#anchor`) are\n   * always internal.\n   *\n   * Omitting this field keeps the output byte-for-byte identical to the\n   * pre-feature behaviour.\n   *\n   * Mirrors `ExternalLinksConfig` in crates/zfb/src/config.rs.\n   */\n  externalLinks?: ExternalLinksConfig;\n\n  /**\n   * Enable CJK-friendly markdown handling.\n   *\n   * Governs two post-parse fixups that adapt CommonMark/GFM rules to CJK\n   * text:\n   *\n   * 1. **Emphasis/strong flanking** (`CjkFriendlyPlugin`). CommonMark's\n   *    left-/right-flanking delimiter-run rules treat CJK characters as\n   *    non-whitespace non-punctuation, which causes `**foo**` adjacent to\n   *    CJK text (e.g. `**テスト。**テスト`) to render as literal stars\n   *    instead of `<strong>`.\n   * 2. **Bare-URL autolink boundary** (`CjkAutolinkBoundaryPlugin`,\n   *    zfb#1105). The GFM autolink-literal path grammar terminates only on\n   *    ASCII whitespace, so a bare URL flush against CJK text\n   *    (`詳細はhttps://example.com参照`) swallows the trailing CJK run into\n   *    the `href`. This fixup terminates the link at the first CJK\n   *    character. Only active when `gfm.autolinkLiteral` is also on.\n   *\n   * - **absent / `true` (default):** CJK-friendly handling is on.\n   *   Preserves today's behaviour — existing CJK-content sites are\n   *   unaffected.\n   * - **`false`:** opt-out. Neither plugin is added to the pipeline;\n   *   emphasis markers and bare-URL autolinks adjacent to CJK characters\n   *   follow base CommonMark/GFM rules. Rarely the right choice; provided\n   *   as an escape hatch for projects that need strict CommonMark/GFM\n   *   output.\n   *\n   * **GFM strikethrough** (`~~foo~~`) at CJK boundaries is unaffected\n   * by this toggle — it is handled by markdown-rs's GFM tokeniser, not\n   * by these plugins, and works correctly in both modes.\n   *\n   * Mirrors `MarkdownConfig::cjk_friendly` in crates/zfb/src/config.rs.\n   */\n  cjkFriendly?: boolean;\n\n  /**\n   * Convert every soft line break (a single `\\n` inside a paragraph) into\n   * `<br>` (remark-breaks parity).\n   *\n   * - **absent / `false` (default):** soft line breaks follow standard\n   *   CommonMark behaviour — collapsed into a single space.\n   * - **`true`:** every `\\n` inside a paragraph becomes `<br>`. Use this\n   *   when your content relies on newline→`<br>` fidelity (e.g. product\n   *   descriptions, lyrics, or other newline-sensitive prose).\n   *\n   * Mirrors `MarkdownConfig::hard_breaks` in crates/zfb/src/config.rs.\n   */\n  hardBreaks?: boolean;\n\n  /**\n   * Per-feature markdown pipeline toggles.\n   *\n   * Each field is a [`FeatureToggle`] (`true` / `false` / options object)\n   * or a feature-specific config type (for features that require extra\n   * parameters). Absent / `undefined` means all features are disabled,\n   * preserving the behaviour of the pre-features build byte-for-byte.\n   *\n   * Unknown keys are rejected at deserialization time by the Rust loader\n   * so a typo in `zfb.config.ts` surfaces as a clear error.\n   *\n   * Mirrors `MarkdownFeaturesConfig` in crates/zfb/src/config.rs.\n   */\n  features?: MarkdownFeaturesConfig;\n};\n\n/**\n * Per-feature toggle: `boolean` shorthand or an options object.\n *\n * `true` enables the feature with defaults; `false` (or absent) disables it.\n * The object form carries per-feature options (fields vary by feature and\n * are filled in by each feature's port sub-issue — stubs today).\n *\n * Mirrors `FeatureToggle` in crates/zfb/src/config.rs.\n */\nexport type FeatureToggle = boolean | FeatureOptions;\n\n/**\n * Empty options object for features that accept `{ ... }` but have no\n * user-facing knobs yet. Fields are filled in by each feature's port\n * sub-issue; this stub satisfies the schema shape requirement.\n *\n * Mirrors `FeatureOptions` in crates/zfb/src/config.rs.\n */\nexport type FeatureOptions = Record<string, never>;\n\n/**\n * Options for the `codeEnrichment` feature.\n *\n * All flags default to `true` when the feature is enabled with\n * `codeEnrichment: {}` or when a field is absent.\n *\n * Mirrors `CodeEnrichmentConfig` in `crates/zfb-md-ast/src/features_config.rs`.\n */\nexport type CodeEnrichmentConfig = {\n  /**\n   * Enable diff-marker processing for markers such as `// [!code ++]`\n   * and `// [!code --]`. Default: `true`.\n   */\n  diffMarkers?: boolean;\n  /**\n   * Enable line-highlight processing for fence ranges such as `{1,3-5}`.\n   * Default: `true`.\n   */\n  lineHighlight?: boolean;\n  /**\n   * Enable visible-text word emphasis for slash-delimited fence metadata\n   * such as `/answer/`. Default: `true`.\n   */\n  wordHighlight?: boolean;\n};\n\n/**\n * Options for the `tocExport` feature.\n *\n * Controls which headings are included in the exported `toc` JSON.\n * `maxDepth` is the **absolute** heading depth (2–6):\n *   - `2` → h2 only\n *   - `3` (default) → h2 + h3\n *\n * This differs from `headingMarkerToc.maxDepth`, which counts levels\n * starting from h2. The two features are independent.\n *\n * Mirrors `TocExportConfig` in crates/zfb-md-ast/src/features_config.rs.\n */\nexport type TocExportConfig = {\n  /** Maximum heading depth to include (absolute, 2–6). Default: 3. */\n  maxDepth?: number;\n};\n\n/**\n * Options for the `imageDimensions` feature.\n *\n * Auto-detects and injects `width`/`height` on local `<img>` elements. Raster\n * formats are probed header-only; SVGs are read from their markup\n * (`width`/`height`/`viewBox`).\n *\n * Mirrors `ImageDimensionsConfig` in crates/zfb-md-ast/src/features_config.rs.\n */\nexport type ImageDimensionsConfig = {\n  /**\n   * When `true` (the default), `http://` and `https://` image sources are\n   * silently skipped and not probed for dimensions. Set to `false` only for\n   * testing or unusual setups — remote images require network access at build\n   * time and slow the pipeline.\n   */\n  skipRemote?: boolean;\n};\n\n/**\n * Options for the `linkValidation` feature.\n *\n * Validates internal `[text](file.md#anchor)` and `[text](#anchor)` links at\n * build time. External URLs (`http://`, `https://`, `mailto:`) are always\n * skipped — network validation is out of scope.\n *\n * Mirrors `LinkValidationConfig` in `crates/zfb-md-ast/src/features_config.rs`.\n */\nexport type LinkValidationConfig = {\n  /**\n   * When `true`, broken links are reported as errors (build can fail).\n   * Default: `false` (warn-only).\n   */\n  failOnBroken?: boolean;\n};\n\n/**\n * Options for the `transclude` feature.\n *\n * Enables `:::include{file=\"./path.md\"}` directives that inline another\n * file's parsed mdast at the include site.\n *\n * Mirrors `TranscludeConfig` in crates/zfb-md-ast/src/features_config.rs.\n */\nexport type TranscludeConfig = {\n  /**\n   * Maximum transclusion depth (chain length A→B→C→…).\n   *\n   * A depth of `1` allows only direct includes (the included file itself\n   * cannot include further files). Default: `5`. A cycle (A→B→A) is\n   * always detected regardless of `maxDepth` and treated as an error.\n   */\n  maxDepth?: number;\n};\n\n/**\n * Options for the `readingTime` feature.\n *\n * Mirrors `ReadingTimeOptions` in crates/zfb-md-ast/src/features_config.rs.\n */\nexport type ReadingTimeConfig = {\n  /** Words-per-minute rate for the reading-time estimate. Default: 200. */\n  wpm?: number;\n};\n\n/**\n * `readingTime` feature value: either a `boolean` shorthand or a\n * {@link ReadingTimeConfig} options object.\n *\n * Mirrors `ReadingTimeFeature` in crates/zfb-md-ast/src/features_config.rs.\n */\nexport type ReadingTimeFeature = boolean | ReadingTimeConfig;\n\n/**\n * Per-feature markdown pipeline configuration.\n *\n * All fields are optional; absent = feature disabled, behaviour unchanged\n * from the pre-features build. Unknown keys are rejected at deserialization\n * time by the Rust loader so a typo surfaces as a clear error.\n *\n * Mirrors `MarkdownFeaturesConfig` in crates/zfb/src/config.rs.\n */\nexport type MarkdownFeaturesConfig = {\n  /** GitHub-style alert blocks (`> [!NOTE]`, `> [!WARNING]`, etc.). */\n  githubAlerts?: FeatureToggle;\n\n  /**\n   * Reading-time estimate injected into the document frontmatter.\n   * Accepts `true` / `false` shorthand or `{ wpm: N }` for a custom rate.\n   */\n  readingTime?: ReadingTimeFeature;\n\n  /** Code-block enrichment (copy button, language label, etc.). */\n  codeEnrichment?: CodeEnrichmentConfig;\n\n  /** Grouped code blocks rendered as tabs. */\n  codeTabs?: FeatureToggle;\n\n  /** Ruby annotation support (`{base}^{ruby}` syntax). */\n  ruby?: FeatureToggle;\n\n  /** Export the page TOC as structured data (e.g. for sidebar rendering). */\n  tocExport?: TocExportConfig;\n\n  /** Auto-detect and inject `width`/`height` on `<img>` elements. */\n  imageDimensions?: ImageDimensionsConfig;\n\n  /**\n   * Validate internal links (file-relative paths and anchor fragments) at\n   * build time. External URLs are always skipped — network validation is\n   * out of scope.\n   */\n  linkValidation?: LinkValidationConfig;\n\n  /**\n   * Transclusion of other markdown/MDX files via\n   * `:::include{file=\"./path.md\"}` — NOT the Obsidian `[[path]]` wikilink\n   * syntax.\n   */\n  transclude?: TranscludeConfig;\n\n  /**\n   * Generic `:::name` → component map. You supply the components; no defaults\n   * are registered. Keys are directive names (e.g. `\"foo\"`), values are\n   * {@link DirectiveSpec} (bare component name string or options object).\n   *\n   * Mirrors `directives` in `MarkdownFeaturesConfig` in crates/zfb/src/config.rs.\n   */\n  directives?: Record<string, DirectiveSpec>;\n\n  /** Mermaid diagram rendering. */\n  mermaid?: FeatureToggle;\n\n  /**\n   * Inline heading-marker TOC. Accepts either a `boolean` shorthand\n   * (`true` = enable with defaults, `false` = disable) or a full\n   * {@link TocConfig} options object — same union shape as the Rust\n   * `HeadingMarkerTocFeature` enum.\n   */\n  headingMarkerToc?: HeadingMarkerTocFeature;\n\n  /**\n   * Heading-ID strategy for the always-on `HeadingLinks` plugin.\n   * Absent → `\"flat\"` (the long-standing github-slugger scheme).\n   * `{ strategy: \"hierarchical\" }` opts into ancestor-prefixed anchor\n   * IDs (`## Foo` / `### Moo` / `#### Mew` → `foo`, `foo-moo`,\n   * `foo-moo-mew`) — see {@link HeadingIdsConfig}.\n   */\n  headingIds?: HeadingIdsConfig;\n};\n\n/**\n * Options for the `headingIds` entry in `markdown.features`.\n *\n * Configures the always-on `HeadingLinks` plugin rather than toggling an\n * opt-in feature. Note: switching to `\"hierarchical\"` is anchor-breaking\n * for existing deep links to nested headings.\n *\n * Mirrors `HeadingIdsConfig` in crates/zfb-md-ast/src/features_config.rs.\n */\nexport type HeadingIdsConfig = {\n  /**\n   * `\"flat\"` (default): github-slugger slugs with a per-document dedup\n   * counter shared across h2–h6 (`overview`, `overview-1`, …).\n   * `\"hierarchical\"`: each heading's slug is prefixed with its ancestor\n   * chain and deduped on the full path — anchors become reconstructible\n   * from the heading outline.\n   */\n  strategy?: \"flat\" | \"hierarchical\";\n};\n\n/**\n * `headingMarkerToc` feature value: either a `boolean` shorthand or a\n * full {@link TocConfig} options object.\n *\n * Mirrors `HeadingMarkerTocFeature` in crates/zfb-md-ast/src/features_config.rs.\n */\nexport type HeadingMarkerTocFeature = boolean | TocConfig;\n\n/**\n * Spec for one user-defined directive: either a bare component name string\n * or a full {@link DirectiveFullSpec} options object.\n *\n * Mirrors `DirectiveSpec` in crates/zfb-md-ast/src/features_config.rs.\n */\nexport type DirectiveSpec = string | DirectiveFullSpec;\n\n/**\n * Full options object for one user-defined directive.\n *\n * Mirrors `DirectiveFullSpec` in crates/zfb-md-ast/src/features_config.rs.\n */\nexport type DirectiveFullSpec = {\n  /** JSX component identifier (e.g. `\"Spoiler\"`, `\"Kbd\"`). */\n  component: string;\n  /** Container/leaf/text shape. Defaults to `\"container\"` when absent. */\n  kind?: \"container\" | \"leaf\" | \"text\";\n  /** Whether the bracketed `[label]` becomes a `title` attribute. Defaults to `true`. */\n  titleFromLabel?: boolean;\n};\n\n/**\n * Options for the external-link rewriter (port of `rehype-external-links`).\n *\n * All fields are optional; omitting a field applies the documented default.\n *\n * Mirrors `ExternalLinksConfig` in crates/zfb/src/config.rs.\n */\nexport type ExternalLinksConfig = {\n  /**\n   * `rel` tokens applied to external links.\n   *\n   * Default: `[\"noopener\", \"noreferrer\"]`.\n   *\n   * Tokens are deduplicated (case-insensitive) and merged with any\n   * existing `rel` attribute on the `<a>` element — existing tokens\n   * appear first.\n   */\n  rel?: string[];\n  /**\n   * `target` value for external links.\n   *\n   * Default: `\"_blank\"`.\n   */\n  target?: string;\n};\n\n/**\n * Either the shorthand boolean form (`true` = all GFM constructs on,\n * `false` = all off) or a partial object that toggles individual\n * constructs.\n *\n * Mirrors `GfmFlag` in crates/zfb/src/config.rs.\n */\nexport type GfmFlag = boolean | GfmConstructs;\n\n/**\n * Per-construct opt-in / opt-out for GFM. Every field is optional;\n * omitted fields fall back to the conservative default\n * (`strikethrough: true`, `table: true`, `autolinkLiteral: true`,\n * others `false`).\n *\n * Mirrors `GfmConstructs` in crates/zfb/src/config.rs.\n */\nexport type GfmConstructs = {\n  /** GFM strikethrough (`~~text~~` → `<del>text</del>`). */\n  strikethrough?: boolean;\n  /** GFM pipe-style tables. */\n  table?: boolean;\n  /**\n   * GFM autolink literal — bare URLs like `https://example.com` become\n   * clickable links without `<…>` brackets.\n   */\n  autolinkLiteral?: boolean;\n  /** GFM task list items (`- [x]` / `- [ ]`). */\n  taskListItem?: boolean;\n  /** GFM footnote definitions (`[^ref]: …`). */\n  footnoteDefinition?: boolean;\n};\n\n/**\n * What to do when a `.md`/`.mdx` link cannot be resolved.\n *\n * Mirrors `OnBrokenLinks` in crates/zfb/src/config.rs.\n */\nexport type OnBrokenLinks = \"warn\" | \"error\" | \"ignore\";\n\n/**\n * Config for the markdown link resolver. See\n * [`ZfbConfig.resolveMarkdownLinks`] for the design rationale.\n */\nexport type ResolveMarkdownLinksConfig = {\n  /** Whether to enable link resolution. Default: `false`. */\n  enabled?: boolean;\n\n  /**\n   * Legacy single-dir field. Used only when [`dirs`] is empty. When\n   * non-empty, scanned against the hard-coded `/docs/` route prefix.\n   */\n  docsDir?: string;\n\n  /**\n   * Explicit per-dir source map. Each entry is one collection (e.g.\n   * EN docs at `src/content/docs/` → `/docs/`, JA docs at\n   * `src/content/docs-ja/` → `/ja/docs/`). Takes precedence over\n   * [`docsDir`] when non-empty.\n   */\n  dirs?: ResolveMarkdownLinksDir[];\n\n  /** What to do with unresolved `.md`/`.mdx` links. Default: `\"warn\"`. */\n  onBrokenLinks?: OnBrokenLinks;\n};\n\n/** One source-dir entry for [`ResolveMarkdownLinksConfig.dirs`]. */\nexport type ResolveMarkdownLinksDir = {\n  /**\n   * Directory (relative to project root) whose `.md`/`.mdx` files are\n   * scanned. Must be relative and must not escape the root via `..`.\n   */\n  dir: string;\n\n  /**\n   * Route prefix prepended to each file's slug. Include leading and\n   * trailing slashes (e.g. `\"/docs/\"` or `\"/ja/docs/\"`).\n   */\n  routePrefix: string;\n};\n\n/**\n * Identity helper: returns the supplied config as-is, but typed against\n * [`ZfbConfig`]. Use as the default export of `zfb.config.ts` so editors\n * surface field-level types and typos surface at compile time.\n */\nexport function defineConfig(config: ZfbConfig): ZfbConfig {\n  return config;\n}\n\n/**\n * Preset authoring helper: stamps each object entry in `config.plugins`\n * with `source_package: sourcePackage` so the Rust loader can attribute\n * plugin contributions back to the preset package that provided them.\n *\n * - Only plain-object plugin entries are stamped; non-object entries pass\n *   through unchanged (defensive — the current schema requires objects,\n *   but this guard keeps the helper safe if the schema is ever relaxed).\n * - An entry that ALREADY carries a `source_package` is left untouched, so a\n *   preset composing another `definePreset`-returned preset (by spreading its\n *   `plugins`) keeps the inner preset's provenance instead of clobbering it\n *   with the outer package name (the spread below lets the existing marker win).\n * - When `config.plugins` is absent, the config is returned as-is.\n * - All other fields of `config` pass through unchanged.\n *\n * The key `source_package` (snake_case) mirrors the Rust `PluginConfig`\n * serde field added in T4. `PluginConfig` has no `#[serde(rename_all)]`\n * so the serde key is the field name verbatim — do NOT use camelCase.\n *\n * SYNC REQUIREMENT: keep this implementation behaviourally identical to\n * the stub in crates/zfb-config-loader/js/zfb-config-stub.mjs, which is\n * injected at config-eval time when the user's project does not have the\n * zfb npm package installed locally.\n */\nexport function definePreset(\n  sourcePackage: string,\n  config: Partial<ZfbConfig>,\n): Partial<ZfbConfig> {\n  if (!config.plugins) {\n    return config;\n  }\n  return {\n    ...config,\n    plugins: config.plugins.map((plugin) => {\n      if (plugin !== null && typeof plugin === \"object\" && !Array.isArray(plugin)) {\n        // Default first, then spread the plugin so an existing `source_package`\n        // (from a composed inner preset) wins over the outer package name.\n        return { source_package: sourcePackage, ...plugin };\n      }\n      return plugin;\n    }),\n  };\n}\n"]}

package/dist/content.d.ts

@@ -15,6 +15,27 @@ export interface SnapshotEntry {
     readonly body: string;
     readonly module_specifier: string;
     readonly rel_path: string;
+    /**
+     * Render-artifact metadata, present only when the build ran with
+     * `emitRenderArtifacts` on and only for markdown entries. Mirrors
+     * `crates/zfb-content/src/render_metadata.rs::RenderRegionMetadata`.
+     */
+    readonly render_metadata?: SnapshotRenderMetadata;
+}
+/**
+ * `{ headings, source_digest }` for one content region. `source_digest`
+ * is `"sha256:" + 64 hex` over the entry's RAW on-disk source bytes
+ * (frontmatter included, no BOM strip, no CRLF normalization) — it
+ * identifies the source, not the rendered output. See
+ * `@takazudo/zfb-runtime/snapshot` for the full field documentation.
+ */
+export interface SnapshotRenderMetadata {
+    readonly headings: readonly {
+        readonly depth: number;
+        readonly text: string;
+        readonly slug: string;
+    }[];
+    readonly source_digest: string;
 }
 /**
  * Point-in-time snapshot of every configured collection. Mirrors

package/dist/content.js

@@ -43,7 +43,7 @@
 // loaded synchronously on first fs-path use. Type-only imports below stay
 // at the top because TypeScript erases them at compile time — they leave
 // no runtime traces for esbuild to chase.
-import { jsx } from "react/jsx-runtime";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 import { parseFrontmatter } from "./frontmatter.js";
 // Re-export the parser surface so existing `zfb/content` consumers that
 // import `parseFrontmatter` / `ParsedFrontmatter` from the content
@@ -195,11 +195,73 @@ function buildContentComponent(module_specifier, body) {
             // try to validate; both Preact and React JSX runtimes accept any
             // structural `{ type, props, key }` object on either side of the
             // boundary, and the renderer is the source of truth here.
-            return renderer(mergedProps);
+            const rendered = renderer(mergedProps);
+            // Render-artifact instrumentation (epic #2421). Off by default and
+            // never set outside `zfb build`, so the common path returns the
+            // bridge's value verbatim and the emitted HTML is byte-identical
+            // to a build without the feature.
+            return zfb?.renderArtifacts === true
+                ? wrapInRenderRegion(module_specifier, rendered)
+                : rendered;
         }
         return renderFallback(body);
     };
 }
+/**
+ * Attribute names of the render-region sentinel pair. The
+ * `data-zfb-render-region` / `data-zfb-region-id` namespace is reserved
+ * by the render-artifact contract (epic #2421): the build's extraction
+ * pass is an exact-byte state machine over these two attributes, so
+ * nothing else may emit them.
+ */
+const RENDER_REGION_ATTR = "data-zfb-render-region";
+const REGION_ID_ATTR = "data-zfb-region-id";
+/**
+ * Wrap a bridge-rendered content region in its sentinel pair:
+ *
+ * ```html
+ * <template data-zfb-render-region="start" data-zfb-region-id="<id>"></template>
+ * …region…
+ * <template data-zfb-render-region="end" data-zfb-region-id="<id>"></template>
+ * ```
+ *
+ * `<template>` is inert in every HTML context (its contents are not
+ * rendered and it carries no layout), and the pair is emitted as three
+ * Fragment children with **no text nodes between them** — the extraction
+ * pass slices on exact bytes, so an introduced space or newline would
+ * land inside the captured fragment.
+ *
+ * `id` is the entry's `module_specifier`, the region id the artifact
+ * writer joins its `{ headings, sourceDigest }` metadata on. Repeated
+ * `Content` calls therefore emit sibling pairs sharing one id, and a
+ * `Content` rendered inside another emits properly nested pairs; the
+ * extraction state machine matches identical-id pairs by nesting order.
+ *
+ * **Runtime-agnostic by construction.** `Fragment` / `jsxs` come from
+ * the same `react/jsx-runtime` specifier `mintElement` already uses,
+ * which the engine alias-rewrites to `preact/jsx-runtime` in Preact mode
+ * (bundler.rs `--alias:react/jsx-runtime=preact/jsx-runtime`) — so both
+ * modes get their own real Fragment, and neither imports the other's.
+ * `jsxs` (not `jsx`) is the static-children form: it tells React the
+ * child array is compiler-generated, which is what keeps the runtime
+ * from demanding `key` props on the three children.
+ */
+function wrapInRenderRegion(regionId, rendered) {
+    return jsxs(Fragment, {
+        children: [
+            renderRegionMarker("start", regionId),
+            rendered,
+            renderRegionMarker("end", regionId),
+        ],
+    });
+}
+/** One `<template>` sentinel. See [`wrapInRenderRegion`]. */
+function renderRegionMarker(edge, regionId) {
+    return mintElement("template", {
+        [RENDER_REGION_ATTR]: edge,
+        [REGION_ID_ATTR]: regionId,
+    });
+}
 /**
  * Mint a content element through the per-project JSX runtime.
  *

package/dist/content.js.map

@@ -1 +1 @@
-{"version":3,"file":"content.js","sourceRoot":"","sources":["../src/content.ts"],"names":[],"mappings":"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","sourcesContent":["// `zfb/content` — minimal v0 content collection loader.\n//\n// Reads `*.md` files from a content collection directory, parses YAML\n// frontmatter, and returns typed entries. This is a deliberately small\n// stub so the bundled basic-blog template can call `getCollection(\"blog\")` today;\n// the production path lives in `crates/zfb-content` and will replace this\n// once the JS-runtime decision (ADR-001) lands and the renderer wires the\n// Rust pipeline back through to user code.\n//\n// Scope (v0):\n// - YAML-ish frontmatter only: `key: value`, plus `key:\\n  - item` arrays.\n//   Quoted strings are unwrapped. ISO dates stay as strings.\n// - Body is the post content **after** the closing `---`, returned as raw\n//   text. This is intentionally NOT pre-rendered HTML: the markdown\n//   pipeline lives in the Rust crate and the JS stub does not duplicate\n//   it.\n// - Collection root is resolved from\n//   `process.env.ZFB_CONTENT_ROOT` (set by the dev/build pipeline), or\n//   `<cwd>/content` as a fallback for unit tests and direct invocation.\n//\n// TODO(zfb-content): swap this stub for the runtime-provided implementation\n// once the content engine ships end-to-end.\n\n// `node:fs` and `node:path` are intentionally NOT imported statically at\n// the top level.\n//\n// Why: this module is reachable via the package root (`@takazudo/zfb`) — the\n// barrel re-exports `defaultComponents` / `ContentH2` / etc. from\n// `./content.js`. The islands per-island bundler (`crates/zfb-islands`) walks\n// `import * as Mod from \"@takazudo/zfb\"` and esbuild's static tree-shaker\n// cannot prune a module behind a wildcard barrel access, so the WHOLE\n// content.ts module ends up in the browser-side island bundle. Top-level\n// `node:fs` / `node:path` imports would then fail the bundle with\n// `Could not resolve \"node:fs\"`. Loading them indirectly through a\n// runtime-constructed `createRequire` keeps the Node-runtime fs path\n// working while letting the islands bundler emit browser-safe output.\n// (Discovered while investigating zudolab/zudo-doc#1355 Wave 3 — see also\n// upstream PR #134 / #130 Gap A.) Defense-in-depth: the islands esbuild\n// invocation also passes `--platform=browser --external:node:*` so any\n// stray `node:*` import that does end up in a browser bundle is\n// externalized rather than failing the build.\n//\n// `getCollection` is synchronous per ADR-004, so the node modules are\n// loaded synchronously on first fs-path use. Type-only imports below stay\n// at the top because TypeScript erases them at compile time — they leave\n// no runtime traces for esbuild to chase.\nimport { jsx } from \"react/jsx-runtime\";\n\nimport type * as NodeFs from \"node:fs\";\nimport type * as NodePath from \"node:path\";\n\nimport { parseFrontmatter } from \"./frontmatter.js\";\nimport type { ParsedFrontmatter } from \"./frontmatter.js\";\nimport type { VNode } from \"./jsx-types.js\";\n\n// Re-export the parser surface so existing `zfb/content` consumers that\n// import `parseFrontmatter` / `ParsedFrontmatter` from the content\n// subpath keep working. The implementation now lives in `./frontmatter.ts`\n// (BCI-3 fs-free subpath) — this re-export is the bridge for callers\n// that have not migrated yet.\nexport { parseFrontmatter };\nexport type { ParsedFrontmatter };\n\n// ---------------------------------------------------------------------------\n// In-memory ContentSnapshot bridge (consumed by `@takazudo/zfb-runtime`).\n//\n// At build time, the Rust pipeline produces a `ContentSnapshot` (see\n// `crates/zfb-content/src/content_bridge.rs`) and embeds it into the\n// Worker bundle. On Worker boot, `createPageRouter` calls\n// `setContentSnapshot(snapshot)` (below) before serving the first\n// request. From that point on, `getCollection(name)` resolves from the\n// embedded snapshot rather than the Node `fs` API — required because the\n// workerd / Cloudflare Workers runtime has no filesystem.\n//\n// The fs path remains the source of truth in two contexts:\n//   1. unit tests for this module (no snapshot installed → fs path),\n//   2. dev-preview / direct-Node invocations of `getCollection` outside\n//      the Worker bundle (kept as v0 fallback so older callers still work).\n//\n// Keep [`SnapshotEntry`] / [`Snapshot`] aligned with the Rust struct\n// (`EntrySnapshot` / `ContentSnapshot`) and the runtime-package mirror\n// (`@takazudo/zfb-runtime/snapshot`). Field names are snake_case to\n// match the JSON serialization (`module_specifier`, `rel_path`).\n// ---------------------------------------------------------------------------\n\n/**\n * One entry in an embedded content snapshot. Mirrors\n * `crates/zfb-content/src/content_bridge.rs::EntrySnapshot`. Re-exported\n * by `@takazudo/zfb-runtime/snapshot` for the runtime-side bundle. See\n * that module for field-by-field documentation.\n */\nexport interface SnapshotEntry {\n  readonly slug: string;\n  readonly frontmatter: unknown;\n  readonly body: string;\n  readonly module_specifier: string;\n  readonly rel_path: string;\n}\n\n/**\n * Point-in-time snapshot of every configured collection. Mirrors\n * `crates/zfb-content/src/content_bridge.rs::ContentSnapshot`.\n */\nexport interface Snapshot {\n  readonly collections: Readonly<Record<string, readonly SnapshotEntry[]>>;\n}\n\n/**\n * Where the installed [`Snapshot`] lives.\n *\n * The state hangs off `globalThis.__zfb.contentSnapshot`, NOT a\n * module-level `let`. This matters because under the production worker\n * bundle the consumer's pnpm-strict `node_modules` layout exposes\n * two physical paths to `@takazudo/zfb`:\n *\n *   - top-level `node_modules/@takazudo/zfb` (imported by user pages), AND\n *   - nested `node_modules/.pnpm/@takazudo+zfb-runtime@.../node_modules/\n *     @takazudo/zfb` (imported by `@takazudo/zfb-runtime` itself).\n *\n * The bundler passes `esbuild --preserve-symlinks` whenever a custom\n * `node_modules_dir` is configured (see `crates/zfb-build/src/bundler.rs`\n * around `--external:node:*`), so esbuild treats those two symlink\n * targets as distinct sources and inlines `content.js` TWICE — yielding\n * two module instances of `zfb/content` in the final worker bundle.\n *\n * If `installedSnapshot` were a per-module `let`, `createPageRouter`\n * would install the snapshot on the runtime's copy and `getCollection`\n * (called from a user `paths()` export) would read from the user\n * page's copy — see `undefined`, and fall through to the `node:fs`\n * branch, which then throws because `node:*` is externalized in the\n * worker bundle. This is the regression #442 / #449 surfaced.\n *\n * Routing the slot through `globalThis` makes the snapshot bridge\n * symmetric with the existing `globalThis.__zfb.content` MDX-component\n * bridge (set by the build pipeline at `crates/zfb-build/src/bundler.rs`,\n * read by `Content` below): both pieces of cross-module state share\n * one well-known global, so any number of `zfb/content` module\n * instances in the same JS realm see the same value.\n *\n * Tracked under #449 (production fix for #442); the test-fixture\n * counterpart was #413.\n */\ntype SnapshotBridgeNamespace = {\n  contentSnapshot?: Snapshot | undefined;\n};\n\ntype SnapshotBridgeGlobal = typeof globalThis & {\n  __zfb?: SnapshotBridgeNamespace;\n};\n\n/**\n * Register a [`Snapshot`] so [`getCollection`] resolves from memory.\n *\n * Pass `undefined` to clear (used by tests that need to restore the v0\n * filesystem path between runs). Idempotent: the latest call wins.\n *\n * Stored on `globalThis.__zfb.contentSnapshot` rather than a\n * module-level `let` so a worker bundle that ends up with two\n * `zfb/content` module instances still sees a single shared snapshot —\n * see the [`SnapshotBridgeNamespace`] doc above for the full\n * pnpm-symlink rationale.\n */\nexport function setContentSnapshot(snapshot: Snapshot | undefined): void {\n  const g = globalThis as SnapshotBridgeGlobal;\n  const ns = (g.__zfb ?? {}) as SnapshotBridgeNamespace;\n  ns.contentSnapshot = snapshot;\n  g.__zfb = ns;\n}\n\n/**\n * Read the currently-installed [`Snapshot`], or `undefined` if none is\n * registered. Exposed mostly for tests; production callers should not\n * need to introspect the bridge state.\n *\n * Reads from `globalThis.__zfb.contentSnapshot`; see\n * [`setContentSnapshot`] for why the slot lives on `globalThis`.\n */\nexport function getContentSnapshot(): Snapshot | undefined {\n  return (globalThis as SnapshotBridgeGlobal).__zfb?.contentSnapshot;\n}\n\n/**\n * Flat map of element-name → override component, used by both\n * [`ContentProps.components`] and the global slot\n * (`globalThis.__zfb?.mdxComponents`). Keys are lowercase HTML tag names\n * (`h2`, `p`, `a`, …) or PascalCase custom-component names.\n */\nexport type MdxComponents = Record<string, unknown>;\n\n/**\n * Props accepted by an entry's [`CollectionEntry.Content`] component.\n *\n * `components` mirrors Astro's `<Content components={...}>` contract:\n * a flat record of element-name → override component (e.g. `{ h1: MyH1 }`).\n * The default-components convention ships from `zfb`'s root export\n * (`defaultComponents`, lands in Sub 6) and users compose with their own\n * via `{ ...defaultComponents, ...mine }`.\n */\nexport interface ContentProps {\n  /** Element-name → override component map. Optional. */\n  components?: MdxComponents;\n}\n\n/**\n * Public JSX-element shape returned by [`CollectionEntry.Content`].\n *\n * Matches the structural shape that both Preact's and React's `jsx-runtime`\n * accept on either side of the boundary, mirroring the Island wrapper's\n * approach. Consumers should treat this as opaque — its only contract is\n * \"renderable JSX value\".\n *\n * Aliased as `JSX.Element` in the field signature: the JS runtime is\n * type-erased and the actual VNode shape is supplied by the framework\n * adapter at evaluation time.\n */\nexport type ContentElement = {\n  readonly type: string | ((...args: unknown[]) => unknown);\n  readonly props: Readonly<Record<string, unknown>>;\n  readonly key: unknown;\n};\n\n/**\n * Bridge contract published by the Rust-side `zfb-render` `Renderer` before\n * evaluating each page module. Cross-referenced from the Rust side in\n * `crates/zfb-render/src/loader.rs` so the two halves stay in sync — see\n * `packages/zfb/CONTRIBUTING.md` for the full contract narrative.\n *\n * The renderer installs `globalThis.__zfb.content.get(specifier)` keyed on\n * the entry's `module_specifier` (Sub 4 convention: `mdx://<collection>/<slug>#<hash>`,\n * collapsed to `mdx://<collection>/<slug>` from the JS stub side which has\n * no hash to compute). When `get` returns `undefined` (or the bridge as a\n * whole is absent — typical of unit tests, dev sandboxes, and any\n * non-renderer evaluation context), `Content` renders a clearly-marked\n * `<pre data-zfb-content-fallback>` fallback so the visual distinction is\n * obvious even in unstyled environments.\n */\ntype ContentBridge = {\n  get(specifier: string): ((props: ContentProps) => unknown) | undefined;\n};\n\ntype ZfbBridgeNamespace = {\n  content?: ContentBridge;\n  /**\n   * Global component-override slot. Populated by sub-task A2 (bridge\n   * installer); A1 only reads it. Absent ⇒ no-op in the merge.\n   */\n  mdxComponents?: MdxComponents;\n};\n\ntype BridgeGlobal = typeof globalThis & {\n  __zfb?: ZfbBridgeNamespace;\n};\n\n/**\n * Generic shape returned for one entry in a content collection. The `data`\n * field carries parsed frontmatter, typed by the caller via the generic\n * parameter.\n */\nexport type CollectionEntry<T = Record<string, unknown>> = {\n  /** Filename without `.md` extension. Stable across runs. */\n  slug: string;\n  /** Parsed frontmatter. */\n  data: T;\n  /** Raw markdown body (frontmatter stripped). */\n  body: string;\n  /**\n   * Stable module specifier used as the bridge lookup key. Format:\n   * `mdx://<collection>/<slug>` (no hash component — the JS stub does\n   * not compile MDX, so it has no body hash to attach; the production\n   * Rust-side `zfb-content::collection::Entry::module_specifier` adds a\n   * `#<hash>` suffix and the bridge is responsible for matching either\n   * form against its registered components).\n   *\n   * This field is part of the v0+ JS surface so the bridge has something\n   * deterministic to key on without consulting per-call state.\n   */\n  module_specifier: string;\n  /**\n   * Renderable component for this entry.\n   *\n   * **Bridge contract.** At call time, `Content` consults\n   * `globalThis.__zfb?.content?.get(entry.module_specifier)`. If the\n   * bridge is present and returns a function, that function is invoked\n   * with `props` and its result returned verbatim.\n   *\n   * **Fallback.** Outside the renderer (unit tests, dev sandboxes, or any\n   * environment where `globalThis.__zfb.content.get` is absent or returns\n   * `undefined`), `Content` returns a JSX-shaped element rendering the\n   * raw markdown body inside a `<pre data-zfb-content-fallback>` block,\n   * with a leading `[zfb fallback render]` marker line so the visual\n   * distinction survives unstyled environments. The marker is also a\n   * grep target for \"did the production renderer not run?\" diagnostics.\n   *\n   * **Typed signature.** Returns `ContentElement` (a structural alias for\n   * `JSX.Element`) so consumers can drop `<entry.Content components={...} />`\n   * into both React and Preact JSX without per-framework type setup.\n   *\n   * @example\n   *   const post = (await getCollection(\"blog\"))[0];\n   *   return <post.Content components={{ ...defaultComponents, h1: MyH1 }} />;\n   */\n  Content: (props: ContentProps) => ContentElement;\n};\n\n// Cached node:fs / node:path module references. Populated lazily on first\n// fs-path use (see [`loadNodeModules`]); reused on subsequent calls.\nlet cachedNodeFs: typeof NodeFs | undefined;\nlet cachedNodePath: typeof NodePath | undefined;\n\n/**\n * Synchronously load `node:fs` and `node:path`, caching the results.\n *\n * The node specifiers are concatenated at runtime (`\"node:\" + \"fs\"`) so\n * esbuild's static analyzer cannot follow them — that's the load-bearing\n * detail here, because this module is reachable from browser-bundled\n * island chains via the `@takazudo/zfb` root barrel (see top-of-file note).\n *\n * Uses CommonJS `require` via [`createRequire`] (stable, sync) rather than\n * `await import()` (async, would force `getCollection` async and violate\n * ADR-004). `createRequire` itself is fetched from `node:module` through\n * the same runtime-built specifier pattern.\n *\n * If `createRequire` cannot be obtained at all (i.e. truly running in a\n * browser-shaped runtime — which would mean a misconfigured island\n * bundle), throws so the failure is loud rather than silent.\n */\nfunction loadNodeModules(): { fs: typeof NodeFs; path: typeof NodePath } {\n  if (cachedNodeFs !== undefined && cachedNodePath !== undefined) {\n    return { fs: cachedNodeFs, path: cachedNodePath };\n  }\n  // Runtime-built specifiers: opaque to esbuild's static analyzer.\n  const moduleSpecifier = \"node:\" + \"module\";\n  const fsSpecifier = \"node:\" + \"fs\";\n  const pathSpecifier = \"node:\" + \"path\";\n  // Strategy A: prefer the host `require` from a CommonJS context. We\n  // probe via `globalThis` and `Function`-built lookup so neither esbuild\n  // nor stricter ESM tooling errors out at the lookup site.\n  const dynamicGlobal = globalThis as unknown as { require?: NodeJS.Require };\n  let nodeRequire: NodeJS.Require | undefined = dynamicGlobal.require;\n  // Strategy B: ESM context — synthesize a require via `node:module`'s\n  // `createRequire`. Loading `node:module` itself through the same\n  // dynamic specifier shields it from esbuild's static walker.\n  if (typeof nodeRequire !== \"function\") {\n    // `Function(\"return require\")()` returns the enclosing `require` when\n    // the bundler/loader injects one (Node CJS, esbuild default). Falls\n    // through if undefined — caught below.\n    try {\n      nodeRequire = new Function(\"return typeof require === 'function' ? require : undefined\")() as\n        | NodeJS.Require\n        | undefined;\n    } catch {\n      nodeRequire = undefined;\n    }\n  }\n  if (typeof nodeRequire !== \"function\") {\n    // Last resort: synthesize via createRequire. Reaches `node:module`\n    // through a dynamic require we have to bootstrap somehow — the only\n    // way without a static `import` is `process.getBuiltinModule` (Node\n    // 22+) which exposes built-ins synchronously without a require.\n    const proc = (\n      globalThis as unknown as { process?: { getBuiltinModule?: (id: string) => unknown } }\n    ).process;\n    const getBuiltin = proc?.getBuiltinModule;\n    if (typeof getBuiltin === \"function\") {\n      const mod = getBuiltin(moduleSpecifier) as typeof import(\"node:module\");\n      nodeRequire = mod.createRequire(import.meta.url);\n    }\n  }\n  if (typeof nodeRequire !== \"function\") {\n    throw new Error(\n      \"zfb/content: cannot load node:fs / node:path — no Node-style require available. \" +\n        \"This module's filesystem path requires a Node runtime; if you see this in a browser \" +\n        \"bundle, the bundler should externalize node:* imports (the islands bundler does so).\",\n    );\n  }\n  cachedNodeFs = nodeRequire(fsSpecifier) as typeof NodeFs;\n  cachedNodePath = nodeRequire(pathSpecifier) as typeof NodePath;\n  return { fs: cachedNodeFs, path: cachedNodePath };\n}\n\n/**\n * Resolve the directory that holds a named content collection. Override\n * via `ZFB_CONTENT_ROOT` so tests / fixtures can point at an arbitrary\n * directory.\n */\nfunction resolveCollectionDir(name: string): string {\n  const { path } = loadNodeModules();\n  const envRoot = process.env[\"ZFB_CONTENT_ROOT\"];\n  const root = envRoot ? path.resolve(envRoot) : path.resolve(process.cwd(), \"content\");\n  return path.join(root, name);\n}\n\n/**\n * Build the v0 stub's bridge specifier for an entry. Mirrors the Rust-side\n * convention (`mdx://<collection>/<slug>`) minus the body hash — the JS\n * stub does not compile MDX, so it has no hash to attach. The bridge\n * resolver on the renderer side is responsible for matching either form.\n */\nfunction buildModuleSpecifier(collection: string, slug: string): string {\n  return `mdx://${collection}/${slug}`;\n}\n\n/**\n * Build the `Content` component for an entry. Captures `module_specifier`\n * + `body` in the closure so the returned function takes only `props`.\n *\n * The bridge lookup is done lazily on every call (not at entry-construction\n * time) so the renderer can install / swap `globalThis.__zfb.content` at\n * any point before the first render without ordering hazards.\n */\nfunction buildContentComponent(\n  module_specifier: string,\n  body: string,\n): (props: ContentProps) => ContentElement {\n  return function Content(props: ContentProps): ContentElement {\n    const zfb = (globalThis as BridgeGlobal).__zfb;\n    const bridge = zfb?.content;\n    const renderer = bridge?.get(module_specifier);\n    if (typeof renderer === \"function\") {\n      // Merge components in documented precedence order before delegating:\n      //   defaultComponents → globalThis.__zfb.mdxComponents → props.components\n      // This is output-neutral because defaultComponents entries are pure\n      // passthroughs; the seam is established here for A2 to populate.\n      const mergedProps: ContentProps = {\n        ...props,\n        components: mergeMdxComponents(zfb?.mdxComponents, props.components),\n      };\n      // Trust the bridge to return a JSX-element-shaped value — we don't\n      // try to validate; both Preact and React JSX runtimes accept any\n      // structural `{ type, props, key }` object on either side of the\n      // boundary, and the renderer is the source of truth here.\n      return renderer(mergedProps) as ContentElement;\n    }\n    return renderFallback(body);\n  };\n}\n\n/**\n * Mint a content element through the per-project JSX runtime.\n *\n * Calls `jsx` from `react/jsx-runtime` — alias-rewritten to\n * `preact/jsx-runtime` in Preact mode by the engine (bundler.rs ~2886),\n * native in React mode — so the returned value is a real element for\n * whichever framework the project configured. This replaces the previous\n * hand-rolled `{ type, props, key, constructor: undefined }` object literal\n * (the Preact diff-path sentinel): that shape made `preact-render-to-string`\n * treat it as a VNode, but React's renderer rejects it as a child with\n * error #31 (\"Objects are not valid as a React child\") because a real React\n * element carries `$$typeof: Symbol.for(\"react.element\")`. `children` is\n * passed inside `props` so a single child or an array both pass through\n * verbatim. Same migration as `Island` in this package. Kept private so\n * callers keep treating `ContentElement` / `ContentComponentElement` as\n * opaque. (Empty-MDX-body history: zudo-doc#505.)\n */\nfunction mintElement(type: string, props: Record<string, unknown>): ContentElement {\n  // `jsx`'s `type` param is typed `ElementType` (string-literal intrinsic\n  // tags or component types), which rejects an arbitrary runtime `string`.\n  // The tag is dynamic here, so cast to the factory's own first-param type —\n  // robust whether the engine aliases `jsx` to react or preact at build time.\n  return jsx(type as Parameters<typeof jsx>[0], props) as unknown as ContentElement;\n}\n\n/**\n * Build the structural JSX element returned when the bridge is absent.\n *\n * Shape: `<pre data-zfb-content-fallback>{marker}\\n{body}</pre>` — the\n * leading `[zfb fallback render]` marker line is part of the public\n * fallback contract (it's both a visual signal and a grep target). Tests\n * pin both the attribute and the marker line.\n */\nfunction renderFallback(body: string): ContentElement {\n  return mintElement(\"pre\", {\n    \"data-zfb-content-fallback\": \"\",\n    children: `${FALLBACK_MARKER}\\n${body}`,\n  });\n}\n\n/** Leading marker line emitted by [`renderFallback`]. Public contract. */\nconst FALLBACK_MARKER = \"[zfb fallback render]\";\n\n/**\n * Load every `*.md` file in the named collection. Files starting with `.`\n * or that lack a `.md` extension are ignored.\n *\n * **ADR-004 contract: this function is synchronous.** TSX page modules\n * call it from anywhere — top-level, inside a render body, inside a\n * `useMemo` — and SSR completes in a single pass without yielding. The\n * snapshot path returns from memory; the filesystem fallback uses sync\n * `node:fs` APIs so the surface stays unified. (The legacy async\n * implementation was an oversight — the ADR predates it; SSG paths\n * always saw a Promise where ADR-004 says they should see an array,\n * which is why migrations from Astro tripped on `getCollection().filter\n * is not a function`.)\n *\n * @example\n *   const posts = getCollection<{ title: string; date: string }>(\"blog\");\n */\nexport function getCollection<T = Record<string, unknown>>(name: string): CollectionEntry<T>[] {\n  // Snapshot path: installed by `@takazudo/zfb-runtime`'s\n  // `createPageRouter` at Worker boot. Worker runtimes have no `fs`, so\n  // this branch is the production path under the embedded V8 host.\n  //\n  // The snapshot lookup reads `globalThis.__zfb.contentSnapshot`\n  // (see `setContentSnapshot` above) rather than a per-module slot so\n  // the cross-`zfb/content`-instance case under `--preserve-symlinks`\n  // resolves through the same shared state — see #449.\n  const installedSnapshot = (globalThis as SnapshotBridgeGlobal).__zfb?.contentSnapshot;\n  if (installedSnapshot !== undefined) {\n    const list = installedSnapshot.collections[name] ?? [];\n    return list.map((entry) => entryFromSnapshot<T>(entry));\n  }\n  // Filesystem fallback (v0 path). Used by unit tests and direct Node\n  // invocations outside the Worker bundle.\n  //\n  // BCI-6: traversal is now recursive — subdirectories are walked so a\n  // collection rooted at `content/blog/` can contain nested `*.md` files\n  // (e.g. `content/blog/2024/hello.md`). Slugs are derived from the\n  // relative path so callers get stable, unique identifiers across nesting\n  // levels.\n  const dir = resolveCollectionDir(name);\n  let mdPaths: string[];\n  try {\n    mdPaths = collectMdFilesSync(dir);\n  } catch (err) {\n    // Guard the `code` access at runtime — a thrown non-`Error` value\n    // (rare, but possible) would otherwise crash here. We only swallow\n    // a true ENOENT; anything else propagates.\n    if (\n      err !== null &&\n      typeof err === \"object\" &&\n      \"code\" in err &&\n      (err as { code: unknown }).code === \"ENOENT\"\n    ) {\n      return [];\n    }\n    throw err;\n  }\n  const { fs, path } = loadNodeModules();\n  return mdPaths.map((fullPath) => {\n    const raw = fs.readFileSync(fullPath, \"utf8\");\n    const { data, body } = parseFrontmatter(raw);\n    // Derive a stable slug from the relative path (relative to collection\n    // root), stripping the `.md` extension. For top-level files this\n    // produces the same value as before; for nested files it produces a\n    // path-based slug (e.g. `2024/hello`).\n    const rel = path.relative(dir, fullPath);\n    const slug = _relPathToSlug(rel);\n    const module_specifier = buildModuleSpecifier(name, slug);\n    return {\n      slug,\n      data: data as T,\n      body,\n      module_specifier,\n      Content: buildContentComponent(module_specifier, body),\n    };\n  });\n}\n\n/**\n * Look up a single entry in a content collection by slug.\n *\n * Thin wrapper over [`getCollection`]: inherits both resolution paths\n * (snapshot via `globalThis.__zfb.contentSnapshot` and the `node:fs`\n * fallback) for free. Returns `undefined` when either the collection does\n * not exist or no entry matches `slug`.\n *\n * **Runtime vs. generated types divergence.** The generated `types.d.ts`\n * emits a keyed overload (`K extends keyof ZfbCollections`) that ties the\n * return type to the collection's declared schema. That schema is enforced\n * by `zfb check`; this runtime form is intentionally structural — it does\n * not reference `ZfbCollections` and does not attempt to reconcile with the\n * keyed shape. (#857)\n *\n * @example\n *   const post = getEntry<{ title: string }>(\"blog\", \"hello-zfb\");\n *   if (!post) return null;\n *   return <post.Content />;\n */\nexport function getEntry<T = Record<string, unknown>>(\n  name: string,\n  slug: string,\n): CollectionEntry<T> | undefined {\n  return getCollection<T>(name).find((e) => e.slug === slug);\n}\n\n/**\n * Construct a [`CollectionEntry`] from a [`SnapshotEntry`]. The snapshot\n * carries `frontmatter` as a possibly-`null` JSON value (matches the\n * Rust contract for entries with no frontmatter); we normalise `null` /\n * `undefined` to an empty object so consumers' `.data.title` reads\n * never have to deal with `null`.\n *\n * **Type-safety note:** `T` is the caller-supplied frontmatter shape\n * but we do **not** validate it at runtime — if the page declares a\n * shape that the actual frontmatter doesn't match, the cast below\n * lies. Callers are expected to keep their `getCollection<MySchema>()`\n * generic in sync with the actual frontmatter; we acknowledge the\n * unsafety with the explicit `unknown` indirection rather than a\n * direct (and silently lossy) cast.\n */\nfunction entryFromSnapshot<T>(entry: SnapshotEntry): CollectionEntry<T> {\n  const data =\n    entry.frontmatter === null || entry.frontmatter === undefined\n      ? ({} as T)\n      : (entry.frontmatter as unknown as T);\n  return {\n    slug: entry.slug,\n    data,\n    body: entry.body,\n    module_specifier: entry.module_specifier,\n    Content: buildContentComponent(entry.module_specifier, entry.body),\n  };\n}\n\n/**\n * Recursively collect every `*.md` file under `dir` (synchronous).\n *\n * BCI-6: replaces the old flat `readdir(dir).filter(n => n.endsWith(\".md\"))`\n * approach. Hidden files (names starting with `.`) and hidden directories\n * are skipped at every nesting level, matching the top-level behaviour of\n * the previous implementation.\n *\n * Returns absolute paths sorted lexicographically so the result order is\n * deterministic across platforms and Node versions.\n *\n * Synchronous to honour ADR-004 — see [`getCollection`].\n */\nfunction collectMdFilesSync(dir: string): string[] {\n  const result: string[] = [];\n  const { fs, path } = loadNodeModules();\n  walkDirSync(fs, path, dir, result);\n  result.sort();\n  return result;\n}\n\nfunction walkDirSync(\n  fs: typeof NodeFs,\n  path: typeof NodePath,\n  current: string,\n  out: string[],\n): void {\n  const entries = fs.readdirSync(current, { withFileTypes: true });\n  for (const entry of entries) {\n    if (entry.name.startsWith(\".\")) continue;\n    const fullPath = path.join(current, entry.name);\n    // Skip symlinks to avoid infinite loops caused by cycles (e.g. a symlink\n    // pointing at a parent directory). Content files are expected to be plain\n    // regular files; following symlinks provides no value here.\n    if (entry.isSymbolicLink()) continue;\n    if (entry.isDirectory()) {\n      walkDirSync(fs, path, fullPath, out);\n    } else if (entry.isFile() && entry.name.endsWith(\".md\")) {\n      out.push(fullPath);\n    }\n  }\n}\n\n/**\n * @internal\n *\n * Convert a `path.relative()` result into a forward-slash-separated\n * slug with the trailing `.md` extension stripped.\n *\n * Slugs are URL-flavored identifiers, not filesystem paths — they\n * MUST use `/` regardless of the host OS so a nested entry like\n * `2024/hello.md` produces the slug `2024/hello` on both POSIX and\n * Windows. Without this normalisation, Windows callers would see\n * `2024\\hello`, which then leaks through to `module_specifier` and\n * any URL the consumer derives from the slug.\n *\n * Exported solely so the unit test suite can pin the Windows\n * behaviour without needing an actual Windows host. Do not depend on\n * this from application code — name and signature may change.\n */\nexport function _relPathToSlug(relPath: string): string {\n  const { path } = loadNodeModules();\n  const posix = path.sep === \"/\" ? relPath : relPath.split(path.sep).join(\"/\");\n  // Some Node versions normalise `\\` even when sep is `/`, so be\n  // defensive: collapse any straggling backslashes too.\n  const normalised = posix.includes(\"\\\\\") ? posix.split(\"\\\\\").join(\"/\") : posix;\n  return normalised.endsWith(\".md\") ? normalised.slice(0, -\".md\".length) : normalised;\n}\n\n// ---------------------------------------------------------------------------\n// `defaultComponents` — htmlOverrides convention\n//\n// Ported from zudo-doc's `src/components/content/component-map.ts`. Users opt\n// in by spreading the map into their own `components` prop:\n//\n//   import { defaultComponents } from \"zfb\";\n//   <entry.Content components={{ ...defaultComponents, h2: MyH2 }} />\n//\n// Each component is a thin passthrough mirroring its zudo-doc counterpart\n// (e.g. `ContentParagraph` → `<p {...rest}>{children}</p>`). v0 ships the\n// passthroughs unstyled; layering smart-break / heading-anchor / link-icon\n// behaviour on top is independent follow-up — keeping the v0 deliverable\n// focused on infrastructure (issue #33).\n//\n// **`h1` is deliberately not in the map** — page titles render `<h1>` from\n// frontmatter, per the zudo-doc convention. Adding `h1` here would silently\n// double-render the page title.\n//\n// **Each override is exported as a named const AND included in\n// `defaultComponents`** so consumers can tree-shake-import a single component\n// (`import { ContentLink } from \"zfb\"`) without dragging in the whole map.\n//\n// Implementation note: components return the structural JSX-element shape\n// directly — same pattern as `Island`. This keeps the package\n// JSX-runtime-agnostic so it works under either Preact or React without\n// importing a runtime. Both `jsx-runtime` implementations accept the\n// `{ type, props, key }` object on either side of the boundary.\n// ---------------------------------------------------------------------------\n\n/**\n * Public JSX-element shape returned by every override in [`defaultComponents`].\n *\n * Mirrors [`ContentElement`] and [`IslandElement`]: a structural alias for\n * `JSX.Element` so consumers can drop these overrides into both React and\n * Preact JSX without per-framework type setup.\n */\nexport type ContentComponentElement = {\n  readonly type: string;\n  readonly props: Readonly<Record<string, unknown>>;\n  readonly key: unknown;\n};\n\n/**\n * Props accepted by every default override. `children` and any extra\n * attributes (`className`, `id`, `href`, …) are passed through verbatim\n * to the underlying HTML element.\n */\nexport interface ContentComponentProps {\n  children?: VNode;\n  [key: string]: unknown;\n}\n\n/** Internal helper: build a structural JSX element of the given tag. */\nfunction buildOverrideElement(tag: string, props: ContentComponentProps): ContentComponentElement {\n  const { children, ...rest } = props;\n  // Minted through the per-project JSX runtime (`mintElement`) so the\n  // override is a real element under both React and Preact — see the\n  // helper's docblock (zudo-doc#505; React error #31 rationale).\n  return mintElement(tag, { ...rest, children }) as unknown as ContentComponentElement;\n}\n\n/**\n * `<h2>` passthrough override. Ported from zudo-doc's `HeadingH2`, stripped\n * of styling — v0 ships pass-through behaviour; visual treatment is layered\n * on by the consumer (or by a follow-up enhancement pass).\n */\nexport function ContentH2(props: ContentComponentProps): ContentComponentElement {\n  return buildOverrideElement(\"h2\", props);\n}\n\n/** `<h3>` passthrough override. See [`ContentH2`] for the contract. */\nexport function ContentH3(props: ContentComponentProps): ContentComponentElement {\n  return buildOverrideElement(\"h3\", props);\n}\n\n/** `<h4>` passthrough override. See [`ContentH2`] for the contract. */\nexport function ContentH4(props: ContentComponentProps): ContentComponentElement {\n  return buildOverrideElement(\"h4\", props);\n}\n\n/** `<p>` passthrough override. Mirrors zudo-doc's `ContentParagraph`. */\nexport function ContentParagraph(props: ContentComponentProps): ContentComponentElement {\n  return buildOverrideElement(\"p\", props);\n}\n\n/** `<a>` passthrough override. Mirrors zudo-doc's `ContentLink`. */\nexport function ContentLink(props: ContentComponentProps): ContentComponentElement {\n  return buildOverrideElement(\"a\", props);\n}\n\n/** `<strong>` passthrough override. Mirrors zudo-doc's `ContentStrong`. */\nexport function ContentStrong(props: ContentComponentProps): ContentComponentElement {\n  return buildOverrideElement(\"strong\", props);\n}\n\n/** `<blockquote>` passthrough override. Mirrors zudo-doc's `ContentBlockquote`. */\nexport function ContentBlockquote(props: ContentComponentProps): ContentComponentElement {\n  return buildOverrideElement(\"blockquote\", props);\n}\n\n/** `<ul>` passthrough override. Mirrors zudo-doc's `ContentUl`. */\nexport function ContentUl(props: ContentComponentProps): ContentComponentElement {\n  return buildOverrideElement(\"ul\", props);\n}\n\n/** `<ol>` passthrough override. Mirrors zudo-doc's `ContentOl`. */\nexport function ContentOl(props: ContentComponentProps): ContentComponentElement {\n  return buildOverrideElement(\"ol\", props);\n}\n\n/** `<table>` passthrough override. Mirrors zudo-doc's `ContentTable`. */\nexport function ContentTable(props: ContentComponentProps): ContentComponentElement {\n  return buildOverrideElement(\"table\", props);\n}\n\n/** `<code>` passthrough override. Mirrors zudo-doc's `ContentCode`. */\nexport function ContentCode(props: ContentComponentProps): ContentComponentElement {\n  return buildOverrideElement(\"code\", props);\n}\n\n/**\n * Default per-element override map — eleven entries covering the markdown\n * tags the zudo-doc convention overrides (`h2`, `h3`, `h4`, `p`, `a`,\n * `strong`, `blockquote`, `ul`, `ol`, `table`, `code`).\n *\n * `h1` is intentionally absent: page titles render from frontmatter, per\n * the zudo-doc convention.\n *\n * Spread into a `components` prop to compose with custom overrides:\n *\n * ```tsx\n * import { defaultComponents } from \"zfb\";\n *\n * <entry.Content components={{ ...defaultComponents, h2: MyFancyH2 }} />\n * ```\n */\nexport const defaultComponents = {\n  h2: ContentH2,\n  h3: ContentH3,\n  h4: ContentH4,\n  p: ContentParagraph,\n  a: ContentLink,\n  strong: ContentStrong,\n  blockquote: ContentBlockquote,\n  ul: ContentUl,\n  ol: ContentOl,\n  table: ContentTable,\n  code: ContentCode,\n} as const;\n\n/**\n * Merge component maps with the documented precedence order:\n * built-in `defaultComponents` → global slot (`globalThis.__zfb?.mdxComponents`)\n * → per-call `props.components`.\n *\n * Spread in stable key order so the resulting map is deterministic; later\n * entries in the spread win on collision (lowest → highest priority). Absent\n * layers (`undefined`) are no-ops via spread-of-undefined.\n *\n * **Output-neutral by design:** `defaultComponents` entries are pure\n * passthroughs (e.g. `ContentH2` → `<h2>{...props}</h2>`), so introducing\n * this merge into `buildContentComponent` does not change the rendered output.\n */\nexport function mergeMdxComponents(\n  globalSlot: MdxComponents | undefined,\n  perCall: MdxComponents | undefined,\n): MdxComponents {\n  return { ...defaultComponents, ...globalSlot, ...perCall };\n}\n"]}
+{"version":3,"file":"content.js","sourceRoot":"","sources":["../src/content.ts"],"names":[],"mappings":"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","sourcesContent":["// `zfb/content` — minimal v0 content collection loader.\n//\n// Reads `*.md` files from a content collection directory, parses YAML\n// frontmatter, and returns typed entries. This is a deliberately small\n// stub so the bundled basic-blog template can call `getCollection(\"blog\")` today;\n// the production path lives in `crates/zfb-content` and will replace this\n// once the JS-runtime decision (ADR-001) lands and the renderer wires the\n// Rust pipeline back through to user code.\n//\n// Scope (v0):\n// - YAML-ish frontmatter only: `key: value`, plus `key:\\n  - item` arrays.\n//   Quoted strings are unwrapped. ISO dates stay as strings.\n// - Body is the post content **after** the closing `---`, returned as raw\n//   text. This is intentionally NOT pre-rendered HTML: the markdown\n//   pipeline lives in the Rust crate and the JS stub does not duplicate\n//   it.\n// - Collection root is resolved from\n//   `process.env.ZFB_CONTENT_ROOT` (set by the dev/build pipeline), or\n//   `<cwd>/content` as a fallback for unit tests and direct invocation.\n//\n// TODO(zfb-content): swap this stub for the runtime-provided implementation\n// once the content engine ships end-to-end.\n\n// `node:fs` and `node:path` are intentionally NOT imported statically at\n// the top level.\n//\n// Why: this module is reachable via the package root (`@takazudo/zfb`) — the\n// barrel re-exports `defaultComponents` / `ContentH2` / etc. from\n// `./content.js`. The islands per-island bundler (`crates/zfb-islands`) walks\n// `import * as Mod from \"@takazudo/zfb\"` and esbuild's static tree-shaker\n// cannot prune a module behind a wildcard barrel access, so the WHOLE\n// content.ts module ends up in the browser-side island bundle. Top-level\n// `node:fs` / `node:path` imports would then fail the bundle with\n// `Could not resolve \"node:fs\"`. Loading them indirectly through a\n// runtime-constructed `createRequire` keeps the Node-runtime fs path\n// working while letting the islands bundler emit browser-safe output.\n// (Discovered while investigating zudolab/zudo-doc#1355 Wave 3 — see also\n// upstream PR #134 / #130 Gap A.) Defense-in-depth: the islands esbuild\n// invocation also passes `--platform=browser --external:node:*` so any\n// stray `node:*` import that does end up in a browser bundle is\n// externalized rather than failing the build.\n//\n// `getCollection` is synchronous per ADR-004, so the node modules are\n// loaded synchronously on first fs-path use. Type-only imports below stay\n// at the top because TypeScript erases them at compile time — they leave\n// no runtime traces for esbuild to chase.\nimport { Fragment, jsx, jsxs } from \"react/jsx-runtime\";\n\nimport type * as NodeFs from \"node:fs\";\nimport type * as NodePath from \"node:path\";\n\nimport { parseFrontmatter } from \"./frontmatter.js\";\nimport type { ParsedFrontmatter } from \"./frontmatter.js\";\nimport type { VNode } from \"./jsx-types.js\";\n\n// Re-export the parser surface so existing `zfb/content` consumers that\n// import `parseFrontmatter` / `ParsedFrontmatter` from the content\n// subpath keep working. The implementation now lives in `./frontmatter.ts`\n// (BCI-3 fs-free subpath) — this re-export is the bridge for callers\n// that have not migrated yet.\nexport { parseFrontmatter };\nexport type { ParsedFrontmatter };\n\n// ---------------------------------------------------------------------------\n// In-memory ContentSnapshot bridge (consumed by `@takazudo/zfb-runtime`).\n//\n// At build time, the Rust pipeline produces a `ContentSnapshot` (see\n// `crates/zfb-content/src/content_bridge.rs`) and embeds it into the\n// Worker bundle. On Worker boot, `createPageRouter` calls\n// `setContentSnapshot(snapshot)` (below) before serving the first\n// request. From that point on, `getCollection(name)` resolves from the\n// embedded snapshot rather than the Node `fs` API — required because the\n// workerd / Cloudflare Workers runtime has no filesystem.\n//\n// The fs path remains the source of truth in two contexts:\n//   1. unit tests for this module (no snapshot installed → fs path),\n//   2. dev-preview / direct-Node invocations of `getCollection` outside\n//      the Worker bundle (kept as v0 fallback so older callers still work).\n//\n// Keep [`SnapshotEntry`] / [`Snapshot`] aligned with the Rust struct\n// (`EntrySnapshot` / `ContentSnapshot`) and the runtime-package mirror\n// (`@takazudo/zfb-runtime/snapshot`). Field names are snake_case to\n// match the JSON serialization (`module_specifier`, `rel_path`).\n// ---------------------------------------------------------------------------\n\n/**\n * One entry in an embedded content snapshot. Mirrors\n * `crates/zfb-content/src/content_bridge.rs::EntrySnapshot`. Re-exported\n * by `@takazudo/zfb-runtime/snapshot` for the runtime-side bundle. See\n * that module for field-by-field documentation.\n */\nexport interface SnapshotEntry {\n  readonly slug: string;\n  readonly frontmatter: unknown;\n  readonly body: string;\n  readonly module_specifier: string;\n  readonly rel_path: string;\n  /**\n   * Render-artifact metadata, present only when the build ran with\n   * `emitRenderArtifacts` on and only for markdown entries. Mirrors\n   * `crates/zfb-content/src/render_metadata.rs::RenderRegionMetadata`.\n   */\n  readonly render_metadata?: SnapshotRenderMetadata;\n}\n\n/**\n * `{ headings, source_digest }` for one content region. `source_digest`\n * is `\"sha256:\" + 64 hex` over the entry's RAW on-disk source bytes\n * (frontmatter included, no BOM strip, no CRLF normalization) — it\n * identifies the source, not the rendered output. See\n * `@takazudo/zfb-runtime/snapshot` for the full field documentation.\n */\nexport interface SnapshotRenderMetadata {\n  readonly headings: readonly {\n    readonly depth: number;\n    readonly text: string;\n    readonly slug: string;\n  }[];\n  readonly source_digest: string;\n}\n\n/**\n * Point-in-time snapshot of every configured collection. Mirrors\n * `crates/zfb-content/src/content_bridge.rs::ContentSnapshot`.\n */\nexport interface Snapshot {\n  readonly collections: Readonly<Record<string, readonly SnapshotEntry[]>>;\n}\n\n/**\n * Where the installed [`Snapshot`] lives.\n *\n * The state hangs off `globalThis.__zfb.contentSnapshot`, NOT a\n * module-level `let`. This matters because under the production worker\n * bundle the consumer's pnpm-strict `node_modules` layout exposes\n * two physical paths to `@takazudo/zfb`:\n *\n *   - top-level `node_modules/@takazudo/zfb` (imported by user pages), AND\n *   - nested `node_modules/.pnpm/@takazudo+zfb-runtime@.../node_modules/\n *     @takazudo/zfb` (imported by `@takazudo/zfb-runtime` itself).\n *\n * The bundler passes `esbuild --preserve-symlinks` whenever a custom\n * `node_modules_dir` is configured (see `crates/zfb-build/src/bundler.rs`\n * around `--external:node:*`), so esbuild treats those two symlink\n * targets as distinct sources and inlines `content.js` TWICE — yielding\n * two module instances of `zfb/content` in the final worker bundle.\n *\n * If `installedSnapshot` were a per-module `let`, `createPageRouter`\n * would install the snapshot on the runtime's copy and `getCollection`\n * (called from a user `paths()` export) would read from the user\n * page's copy — see `undefined`, and fall through to the `node:fs`\n * branch, which then throws because `node:*` is externalized in the\n * worker bundle. This is the regression #442 / #449 surfaced.\n *\n * Routing the slot through `globalThis` makes the snapshot bridge\n * symmetric with the existing `globalThis.__zfb.content` MDX-component\n * bridge (set by the build pipeline at `crates/zfb-build/src/bundler.rs`,\n * read by `Content` below): both pieces of cross-module state share\n * one well-known global, so any number of `zfb/content` module\n * instances in the same JS realm see the same value.\n *\n * Tracked under #449 (production fix for #442); the test-fixture\n * counterpart was #413.\n */\ntype SnapshotBridgeNamespace = {\n  contentSnapshot?: Snapshot | undefined;\n};\n\ntype SnapshotBridgeGlobal = typeof globalThis & {\n  __zfb?: SnapshotBridgeNamespace;\n};\n\n/**\n * Register a [`Snapshot`] so [`getCollection`] resolves from memory.\n *\n * Pass `undefined` to clear (used by tests that need to restore the v0\n * filesystem path between runs). Idempotent: the latest call wins.\n *\n * Stored on `globalThis.__zfb.contentSnapshot` rather than a\n * module-level `let` so a worker bundle that ends up with two\n * `zfb/content` module instances still sees a single shared snapshot —\n * see the [`SnapshotBridgeNamespace`] doc above for the full\n * pnpm-symlink rationale.\n */\nexport function setContentSnapshot(snapshot: Snapshot | undefined): void {\n  const g = globalThis as SnapshotBridgeGlobal;\n  const ns = (g.__zfb ?? {}) as SnapshotBridgeNamespace;\n  ns.contentSnapshot = snapshot;\n  g.__zfb = ns;\n}\n\n/**\n * Read the currently-installed [`Snapshot`], or `undefined` if none is\n * registered. Exposed mostly for tests; production callers should not\n * need to introspect the bridge state.\n *\n * Reads from `globalThis.__zfb.contentSnapshot`; see\n * [`setContentSnapshot`] for why the slot lives on `globalThis`.\n */\nexport function getContentSnapshot(): Snapshot | undefined {\n  return (globalThis as SnapshotBridgeGlobal).__zfb?.contentSnapshot;\n}\n\n/**\n * Flat map of element-name → override component, used by both\n * [`ContentProps.components`] and the global slot\n * (`globalThis.__zfb?.mdxComponents`). Keys are lowercase HTML tag names\n * (`h2`, `p`, `a`, …) or PascalCase custom-component names.\n */\nexport type MdxComponents = Record<string, unknown>;\n\n/**\n * Props accepted by an entry's [`CollectionEntry.Content`] component.\n *\n * `components` mirrors Astro's `<Content components={...}>` contract:\n * a flat record of element-name → override component (e.g. `{ h1: MyH1 }`).\n * The default-components convention ships from `zfb`'s root export\n * (`defaultComponents`, lands in Sub 6) and users compose with their own\n * via `{ ...defaultComponents, ...mine }`.\n */\nexport interface ContentProps {\n  /** Element-name → override component map. Optional. */\n  components?: MdxComponents;\n}\n\n/**\n * Public JSX-element shape returned by [`CollectionEntry.Content`].\n *\n * Matches the structural shape that both Preact's and React's `jsx-runtime`\n * accept on either side of the boundary, mirroring the Island wrapper's\n * approach. Consumers should treat this as opaque — its only contract is\n * \"renderable JSX value\".\n *\n * Aliased as `JSX.Element` in the field signature: the JS runtime is\n * type-erased and the actual VNode shape is supplied by the framework\n * adapter at evaluation time.\n */\nexport type ContentElement = {\n  readonly type: string | ((...args: unknown[]) => unknown);\n  readonly props: Readonly<Record<string, unknown>>;\n  readonly key: unknown;\n};\n\n/**\n * Bridge contract published by the Rust-side `zfb-render` `Renderer` before\n * evaluating each page module. Cross-referenced from the Rust side in\n * `crates/zfb-render/src/loader.rs` so the two halves stay in sync — see\n * `packages/zfb/CONTRIBUTING.md` for the full contract narrative.\n *\n * The renderer installs `globalThis.__zfb.content.get(specifier)` keyed on\n * the entry's `module_specifier` (Sub 4 convention: `mdx://<collection>/<slug>#<hash>`,\n * collapsed to `mdx://<collection>/<slug>` from the JS stub side which has\n * no hash to compute). When `get` returns `undefined` (or the bridge as a\n * whole is absent — typical of unit tests, dev sandboxes, and any\n * non-renderer evaluation context), `Content` renders a clearly-marked\n * `<pre data-zfb-content-fallback>` fallback so the visual distinction is\n * obvious even in unstyled environments.\n */\ntype ContentBridge = {\n  get(specifier: string): ((props: ContentProps) => unknown) | undefined;\n};\n\ntype ZfbBridgeNamespace = {\n  content?: ContentBridge;\n  /**\n   * Global component-override slot. Populated by sub-task A2 (bridge\n   * installer); A1 only reads it. Absent ⇒ no-op in the merge.\n   */\n  mdxComponents?: MdxComponents;\n  /**\n   * Render-region marker switch (epic #2421). When `true`, every\n   * bridge-resolved `Content` render is wrapped in the inert\n   * `<template data-zfb-render-region>` sentinel pair that the build's\n   * extraction pass slices on — see [`wrapInRenderRegion`].\n   *\n   * **Build-only by construction.** The bundler emits the setter into\n   * the synthetic `entry.mjs` only when the run is `zfb build`\n   * (`BundleMode::Production`) AND `emitRenderArtifacts` resolved on;\n   * `zfb dev` passes `BundleMode::Development`, so the setter's bytes\n   * are never written into a dev bundle. It is never emitted into a\n   * client/island bundle either — `entry.mjs` is the SSR entry.\n   */\n  renderArtifacts?: boolean;\n};\n\ntype BridgeGlobal = typeof globalThis & {\n  __zfb?: ZfbBridgeNamespace;\n};\n\n/**\n * Generic shape returned for one entry in a content collection. The `data`\n * field carries parsed frontmatter, typed by the caller via the generic\n * parameter.\n */\nexport type CollectionEntry<T = Record<string, unknown>> = {\n  /** Filename without `.md` extension. Stable across runs. */\n  slug: string;\n  /** Parsed frontmatter. */\n  data: T;\n  /** Raw markdown body (frontmatter stripped). */\n  body: string;\n  /**\n   * Stable module specifier used as the bridge lookup key. Format:\n   * `mdx://<collection>/<slug>` (no hash component — the JS stub does\n   * not compile MDX, so it has no body hash to attach; the production\n   * Rust-side `zfb-content::collection::Entry::module_specifier` adds a\n   * `#<hash>` suffix and the bridge is responsible for matching either\n   * form against its registered components).\n   *\n   * This field is part of the v0+ JS surface so the bridge has something\n   * deterministic to key on without consulting per-call state.\n   */\n  module_specifier: string;\n  /**\n   * Renderable component for this entry.\n   *\n   * **Bridge contract.** At call time, `Content` consults\n   * `globalThis.__zfb?.content?.get(entry.module_specifier)`. If the\n   * bridge is present and returns a function, that function is invoked\n   * with `props` and its result returned verbatim.\n   *\n   * **Fallback.** Outside the renderer (unit tests, dev sandboxes, or any\n   * environment where `globalThis.__zfb.content.get` is absent or returns\n   * `undefined`), `Content` returns a JSX-shaped element rendering the\n   * raw markdown body inside a `<pre data-zfb-content-fallback>` block,\n   * with a leading `[zfb fallback render]` marker line so the visual\n   * distinction survives unstyled environments. The marker is also a\n   * grep target for \"did the production renderer not run?\" diagnostics.\n   *\n   * **Typed signature.** Returns `ContentElement` (a structural alias for\n   * `JSX.Element`) so consumers can drop `<entry.Content components={...} />`\n   * into both React and Preact JSX without per-framework type setup.\n   *\n   * @example\n   *   const post = (await getCollection(\"blog\"))[0];\n   *   return <post.Content components={{ ...defaultComponents, h1: MyH1 }} />;\n   */\n  Content: (props: ContentProps) => ContentElement;\n};\n\n// Cached node:fs / node:path module references. Populated lazily on first\n// fs-path use (see [`loadNodeModules`]); reused on subsequent calls.\nlet cachedNodeFs: typeof NodeFs | undefined;\nlet cachedNodePath: typeof NodePath | undefined;\n\n/**\n * Synchronously load `node:fs` and `node:path`, caching the results.\n *\n * The node specifiers are concatenated at runtime (`\"node:\" + \"fs\"`) so\n * esbuild's static analyzer cannot follow them — that's the load-bearing\n * detail here, because this module is reachable from browser-bundled\n * island chains via the `@takazudo/zfb` root barrel (see top-of-file note).\n *\n * Uses CommonJS `require` via [`createRequire`] (stable, sync) rather than\n * `await import()` (async, would force `getCollection` async and violate\n * ADR-004). `createRequire` itself is fetched from `node:module` through\n * the same runtime-built specifier pattern.\n *\n * If `createRequire` cannot be obtained at all (i.e. truly running in a\n * browser-shaped runtime — which would mean a misconfigured island\n * bundle), throws so the failure is loud rather than silent.\n */\nfunction loadNodeModules(): { fs: typeof NodeFs; path: typeof NodePath } {\n  if (cachedNodeFs !== undefined && cachedNodePath !== undefined) {\n    return { fs: cachedNodeFs, path: cachedNodePath };\n  }\n  // Runtime-built specifiers: opaque to esbuild's static analyzer.\n  const moduleSpecifier = \"node:\" + \"module\";\n  const fsSpecifier = \"node:\" + \"fs\";\n  const pathSpecifier = \"node:\" + \"path\";\n  // Strategy A: prefer the host `require` from a CommonJS context. We\n  // probe via `globalThis` and `Function`-built lookup so neither esbuild\n  // nor stricter ESM tooling errors out at the lookup site.\n  const dynamicGlobal = globalThis as unknown as { require?: NodeJS.Require };\n  let nodeRequire: NodeJS.Require | undefined = dynamicGlobal.require;\n  // Strategy B: ESM context — synthesize a require via `node:module`'s\n  // `createRequire`. Loading `node:module` itself through the same\n  // dynamic specifier shields it from esbuild's static walker.\n  if (typeof nodeRequire !== \"function\") {\n    // `Function(\"return require\")()` returns the enclosing `require` when\n    // the bundler/loader injects one (Node CJS, esbuild default). Falls\n    // through if undefined — caught below.\n    try {\n      nodeRequire = new Function(\"return typeof require === 'function' ? require : undefined\")() as\n        | NodeJS.Require\n        | undefined;\n    } catch {\n      nodeRequire = undefined;\n    }\n  }\n  if (typeof nodeRequire !== \"function\") {\n    // Last resort: synthesize via createRequire. Reaches `node:module`\n    // through a dynamic require we have to bootstrap somehow — the only\n    // way without a static `import` is `process.getBuiltinModule` (Node\n    // 22+) which exposes built-ins synchronously without a require.\n    const proc = (\n      globalThis as unknown as { process?: { getBuiltinModule?: (id: string) => unknown } }\n    ).process;\n    const getBuiltin = proc?.getBuiltinModule;\n    if (typeof getBuiltin === \"function\") {\n      const mod = getBuiltin(moduleSpecifier) as typeof import(\"node:module\");\n      nodeRequire = mod.createRequire(import.meta.url);\n    }\n  }\n  if (typeof nodeRequire !== \"function\") {\n    throw new Error(\n      \"zfb/content: cannot load node:fs / node:path — no Node-style require available. \" +\n        \"This module's filesystem path requires a Node runtime; if you see this in a browser \" +\n        \"bundle, the bundler should externalize node:* imports (the islands bundler does so).\",\n    );\n  }\n  cachedNodeFs = nodeRequire(fsSpecifier) as typeof NodeFs;\n  cachedNodePath = nodeRequire(pathSpecifier) as typeof NodePath;\n  return { fs: cachedNodeFs, path: cachedNodePath };\n}\n\n/**\n * Resolve the directory that holds a named content collection. Override\n * via `ZFB_CONTENT_ROOT` so tests / fixtures can point at an arbitrary\n * directory.\n */\nfunction resolveCollectionDir(name: string): string {\n  const { path } = loadNodeModules();\n  const envRoot = process.env[\"ZFB_CONTENT_ROOT\"];\n  const root = envRoot ? path.resolve(envRoot) : path.resolve(process.cwd(), \"content\");\n  return path.join(root, name);\n}\n\n/**\n * Build the v0 stub's bridge specifier for an entry. Mirrors the Rust-side\n * convention (`mdx://<collection>/<slug>`) minus the body hash — the JS\n * stub does not compile MDX, so it has no hash to attach. The bridge\n * resolver on the renderer side is responsible for matching either form.\n */\nfunction buildModuleSpecifier(collection: string, slug: string): string {\n  return `mdx://${collection}/${slug}`;\n}\n\n/**\n * Build the `Content` component for an entry. Captures `module_specifier`\n * + `body` in the closure so the returned function takes only `props`.\n *\n * The bridge lookup is done lazily on every call (not at entry-construction\n * time) so the renderer can install / swap `globalThis.__zfb.content` at\n * any point before the first render without ordering hazards.\n */\nfunction buildContentComponent(\n  module_specifier: string,\n  body: string,\n): (props: ContentProps) => ContentElement {\n  return function Content(props: ContentProps): ContentElement {\n    const zfb = (globalThis as BridgeGlobal).__zfb;\n    const bridge = zfb?.content;\n    const renderer = bridge?.get(module_specifier);\n    if (typeof renderer === \"function\") {\n      // Merge components in documented precedence order before delegating:\n      //   defaultComponents → globalThis.__zfb.mdxComponents → props.components\n      // This is output-neutral because defaultComponents entries are pure\n      // passthroughs; the seam is established here for A2 to populate.\n      const mergedProps: ContentProps = {\n        ...props,\n        components: mergeMdxComponents(zfb?.mdxComponents, props.components),\n      };\n      // Trust the bridge to return a JSX-element-shaped value — we don't\n      // try to validate; both Preact and React JSX runtimes accept any\n      // structural `{ type, props, key }` object on either side of the\n      // boundary, and the renderer is the source of truth here.\n      const rendered = renderer(mergedProps) as ContentElement;\n      // Render-artifact instrumentation (epic #2421). Off by default and\n      // never set outside `zfb build`, so the common path returns the\n      // bridge's value verbatim and the emitted HTML is byte-identical\n      // to a build without the feature.\n      return zfb?.renderArtifacts === true\n        ? wrapInRenderRegion(module_specifier, rendered)\n        : rendered;\n    }\n    return renderFallback(body);\n  };\n}\n\n/**\n * Attribute names of the render-region sentinel pair. The\n * `data-zfb-render-region` / `data-zfb-region-id` namespace is reserved\n * by the render-artifact contract (epic #2421): the build's extraction\n * pass is an exact-byte state machine over these two attributes, so\n * nothing else may emit them.\n */\nconst RENDER_REGION_ATTR = \"data-zfb-render-region\";\nconst REGION_ID_ATTR = \"data-zfb-region-id\";\n\n/**\n * Wrap a bridge-rendered content region in its sentinel pair:\n *\n * ```html\n * <template data-zfb-render-region=\"start\" data-zfb-region-id=\"<id>\"></template>\n * …region…\n * <template data-zfb-render-region=\"end\" data-zfb-region-id=\"<id>\"></template>\n * ```\n *\n * `<template>` is inert in every HTML context (its contents are not\n * rendered and it carries no layout), and the pair is emitted as three\n * Fragment children with **no text nodes between them** — the extraction\n * pass slices on exact bytes, so an introduced space or newline would\n * land inside the captured fragment.\n *\n * `id` is the entry's `module_specifier`, the region id the artifact\n * writer joins its `{ headings, sourceDigest }` metadata on. Repeated\n * `Content` calls therefore emit sibling pairs sharing one id, and a\n * `Content` rendered inside another emits properly nested pairs; the\n * extraction state machine matches identical-id pairs by nesting order.\n *\n * **Runtime-agnostic by construction.** `Fragment` / `jsxs` come from\n * the same `react/jsx-runtime` specifier `mintElement` already uses,\n * which the engine alias-rewrites to `preact/jsx-runtime` in Preact mode\n * (bundler.rs `--alias:react/jsx-runtime=preact/jsx-runtime`) — so both\n * modes get their own real Fragment, and neither imports the other's.\n * `jsxs` (not `jsx`) is the static-children form: it tells React the\n * child array is compiler-generated, which is what keeps the runtime\n * from demanding `key` props on the three children.\n */\nfunction wrapInRenderRegion(regionId: string, rendered: ContentElement): ContentElement {\n  return jsxs(Fragment, {\n    children: [\n      renderRegionMarker(\"start\", regionId),\n      rendered,\n      renderRegionMarker(\"end\", regionId),\n    ],\n  }) as unknown as ContentElement;\n}\n\n/** One `<template>` sentinel. See [`wrapInRenderRegion`]. */\nfunction renderRegionMarker(edge: \"start\" | \"end\", regionId: string): ContentElement {\n  return mintElement(\"template\", {\n    [RENDER_REGION_ATTR]: edge,\n    [REGION_ID_ATTR]: regionId,\n  });\n}\n\n/**\n * Mint a content element through the per-project JSX runtime.\n *\n * Calls `jsx` from `react/jsx-runtime` — alias-rewritten to\n * `preact/jsx-runtime` in Preact mode by the engine (bundler.rs ~2886),\n * native in React mode — so the returned value is a real element for\n * whichever framework the project configured. This replaces the previous\n * hand-rolled `{ type, props, key, constructor: undefined }` object literal\n * (the Preact diff-path sentinel): that shape made `preact-render-to-string`\n * treat it as a VNode, but React's renderer rejects it as a child with\n * error #31 (\"Objects are not valid as a React child\") because a real React\n * element carries `$$typeof: Symbol.for(\"react.element\")`. `children` is\n * passed inside `props` so a single child or an array both pass through\n * verbatim. Same migration as `Island` in this package. Kept private so\n * callers keep treating `ContentElement` / `ContentComponentElement` as\n * opaque. (Empty-MDX-body history: zudo-doc#505.)\n */\nfunction mintElement(type: string, props: Record<string, unknown>): ContentElement {\n  // `jsx`'s `type` param is typed `ElementType` (string-literal intrinsic\n  // tags or component types), which rejects an arbitrary runtime `string`.\n  // The tag is dynamic here, so cast to the factory's own first-param type —\n  // robust whether the engine aliases `jsx` to react or preact at build time.\n  return jsx(type as Parameters<typeof jsx>[0], props) as unknown as ContentElement;\n}\n\n/**\n * Build the structural JSX element returned when the bridge is absent.\n *\n * Shape: `<pre data-zfb-content-fallback>{marker}\\n{body}</pre>` — the\n * leading `[zfb fallback render]` marker line is part of the public\n * fallback contract (it's both a visual signal and a grep target). Tests\n * pin both the attribute and the marker line.\n */\nfunction renderFallback(body: string): ContentElement {\n  return mintElement(\"pre\", {\n    \"data-zfb-content-fallback\": \"\",\n    children: `${FALLBACK_MARKER}\\n${body}`,\n  });\n}\n\n/** Leading marker line emitted by [`renderFallback`]. Public contract. */\nconst FALLBACK_MARKER = \"[zfb fallback render]\";\n\n/**\n * Load every `*.md` file in the named collection. Files starting with `.`\n * or that lack a `.md` extension are ignored.\n *\n * **ADR-004 contract: this function is synchronous.** TSX page modules\n * call it from anywhere — top-level, inside a render body, inside a\n * `useMemo` — and SSR completes in a single pass without yielding. The\n * snapshot path returns from memory; the filesystem fallback uses sync\n * `node:fs` APIs so the surface stays unified. (The legacy async\n * implementation was an oversight — the ADR predates it; SSG paths\n * always saw a Promise where ADR-004 says they should see an array,\n * which is why migrations from Astro tripped on `getCollection().filter\n * is not a function`.)\n *\n * @example\n *   const posts = getCollection<{ title: string; date: string }>(\"blog\");\n */\nexport function getCollection<T = Record<string, unknown>>(name: string): CollectionEntry<T>[] {\n  // Snapshot path: installed by `@takazudo/zfb-runtime`'s\n  // `createPageRouter` at Worker boot. Worker runtimes have no `fs`, so\n  // this branch is the production path under the embedded V8 host.\n  //\n  // The snapshot lookup reads `globalThis.__zfb.contentSnapshot`\n  // (see `setContentSnapshot` above) rather than a per-module slot so\n  // the cross-`zfb/content`-instance case under `--preserve-symlinks`\n  // resolves through the same shared state — see #449.\n  const installedSnapshot = (globalThis as SnapshotBridgeGlobal).__zfb?.contentSnapshot;\n  if (installedSnapshot !== undefined) {\n    const list = installedSnapshot.collections[name] ?? [];\n    return list.map((entry) => entryFromSnapshot<T>(entry));\n  }\n  // Filesystem fallback (v0 path). Used by unit tests and direct Node\n  // invocations outside the Worker bundle.\n  //\n  // BCI-6: traversal is now recursive — subdirectories are walked so a\n  // collection rooted at `content/blog/` can contain nested `*.md` files\n  // (e.g. `content/blog/2024/hello.md`). Slugs are derived from the\n  // relative path so callers get stable, unique identifiers across nesting\n  // levels.\n  const dir = resolveCollectionDir(name);\n  let mdPaths: string[];\n  try {\n    mdPaths = collectMdFilesSync(dir);\n  } catch (err) {\n    // Guard the `code` access at runtime — a thrown non-`Error` value\n    // (rare, but possible) would otherwise crash here. We only swallow\n    // a true ENOENT; anything else propagates.\n    if (\n      err !== null &&\n      typeof err === \"object\" &&\n      \"code\" in err &&\n      (err as { code: unknown }).code === \"ENOENT\"\n    ) {\n      return [];\n    }\n    throw err;\n  }\n  const { fs, path } = loadNodeModules();\n  return mdPaths.map((fullPath) => {\n    const raw = fs.readFileSync(fullPath, \"utf8\");\n    const { data, body } = parseFrontmatter(raw);\n    // Derive a stable slug from the relative path (relative to collection\n    // root), stripping the `.md` extension. For top-level files this\n    // produces the same value as before; for nested files it produces a\n    // path-based slug (e.g. `2024/hello`).\n    const rel = path.relative(dir, fullPath);\n    const slug = _relPathToSlug(rel);\n    const module_specifier = buildModuleSpecifier(name, slug);\n    return {\n      slug,\n      data: data as T,\n      body,\n      module_specifier,\n      Content: buildContentComponent(module_specifier, body),\n    };\n  });\n}\n\n/**\n * Look up a single entry in a content collection by slug.\n *\n * Thin wrapper over [`getCollection`]: inherits both resolution paths\n * (snapshot via `globalThis.__zfb.contentSnapshot` and the `node:fs`\n * fallback) for free. Returns `undefined` when either the collection does\n * not exist or no entry matches `slug`.\n *\n * **Runtime vs. generated types divergence.** The generated `types.d.ts`\n * emits a keyed overload (`K extends keyof ZfbCollections`) that ties the\n * return type to the collection's declared schema. That schema is enforced\n * by `zfb check`; this runtime form is intentionally structural — it does\n * not reference `ZfbCollections` and does not attempt to reconcile with the\n * keyed shape. (#857)\n *\n * @example\n *   const post = getEntry<{ title: string }>(\"blog\", \"hello-zfb\");\n *   if (!post) return null;\n *   return <post.Content />;\n */\nexport function getEntry<T = Record<string, unknown>>(\n  name: string,\n  slug: string,\n): CollectionEntry<T> | undefined {\n  return getCollection<T>(name).find((e) => e.slug === slug);\n}\n\n/**\n * Construct a [`CollectionEntry`] from a [`SnapshotEntry`]. The snapshot\n * carries `frontmatter` as a possibly-`null` JSON value (matches the\n * Rust contract for entries with no frontmatter); we normalise `null` /\n * `undefined` to an empty object so consumers' `.data.title` reads\n * never have to deal with `null`.\n *\n * **Type-safety note:** `T` is the caller-supplied frontmatter shape\n * but we do **not** validate it at runtime — if the page declares a\n * shape that the actual frontmatter doesn't match, the cast below\n * lies. Callers are expected to keep their `getCollection<MySchema>()`\n * generic in sync with the actual frontmatter; we acknowledge the\n * unsafety with the explicit `unknown` indirection rather than a\n * direct (and silently lossy) cast.\n */\nfunction entryFromSnapshot<T>(entry: SnapshotEntry): CollectionEntry<T> {\n  const data =\n    entry.frontmatter === null || entry.frontmatter === undefined\n      ? ({} as T)\n      : (entry.frontmatter as unknown as T);\n  return {\n    slug: entry.slug,\n    data,\n    body: entry.body,\n    module_specifier: entry.module_specifier,\n    Content: buildContentComponent(entry.module_specifier, entry.body),\n  };\n}\n\n/**\n * Recursively collect every `*.md` file under `dir` (synchronous).\n *\n * BCI-6: replaces the old flat `readdir(dir).filter(n => n.endsWith(\".md\"))`\n * approach. Hidden files (names starting with `.`) and hidden directories\n * are skipped at every nesting level, matching the top-level behaviour of\n * the previous implementation.\n *\n * Returns absolute paths sorted lexicographically so the result order is\n * deterministic across platforms and Node versions.\n *\n * Synchronous to honour ADR-004 — see [`getCollection`].\n */\nfunction collectMdFilesSync(dir: string): string[] {\n  const result: string[] = [];\n  const { fs, path } = loadNodeModules();\n  walkDirSync(fs, path, dir, result);\n  result.sort();\n  return result;\n}\n\nfunction walkDirSync(\n  fs: typeof NodeFs,\n  path: typeof NodePath,\n  current: string,\n  out: string[],\n): void {\n  const entries = fs.readdirSync(current, { withFileTypes: true });\n  for (const entry of entries) {\n    if (entry.name.startsWith(\".\")) continue;\n    const fullPath = path.join(current, entry.name);\n    // Skip symlinks to avoid infinite loops caused by cycles (e.g. a symlink\n    // pointing at a parent directory). Content files are expected to be plain\n    // regular files; following symlinks provides no value here.\n    if (entry.isSymbolicLink()) continue;\n    if (entry.isDirectory()) {\n      walkDirSync(fs, path, fullPath, out);\n    } else if (entry.isFile() && entry.name.endsWith(\".md\")) {\n      out.push(fullPath);\n    }\n  }\n}\n\n/**\n * @internal\n *\n * Convert a `path.relative()` result into a forward-slash-separated\n * slug with the trailing `.md` extension stripped.\n *\n * Slugs are URL-flavored identifiers, not filesystem paths — they\n * MUST use `/` regardless of the host OS so a nested entry like\n * `2024/hello.md` produces the slug `2024/hello` on both POSIX and\n * Windows. Without this normalisation, Windows callers would see\n * `2024\\hello`, which then leaks through to `module_specifier` and\n * any URL the consumer derives from the slug.\n *\n * Exported solely so the unit test suite can pin the Windows\n * behaviour without needing an actual Windows host. Do not depend on\n * this from application code — name and signature may change.\n */\nexport function _relPathToSlug(relPath: string): string {\n  const { path } = loadNodeModules();\n  const posix = path.sep === \"/\" ? relPath : relPath.split(path.sep).join(\"/\");\n  // Some Node versions normalise `\\` even when sep is `/`, so be\n  // defensive: collapse any straggling backslashes too.\n  const normalised = posix.includes(\"\\\\\") ? posix.split(\"\\\\\").join(\"/\") : posix;\n  return normalised.endsWith(\".md\") ? normalised.slice(0, -\".md\".length) : normalised;\n}\n\n// ---------------------------------------------------------------------------\n// `defaultComponents` — htmlOverrides convention\n//\n// Ported from zudo-doc's `src/components/content/component-map.ts`. Users opt\n// in by spreading the map into their own `components` prop:\n//\n//   import { defaultComponents } from \"zfb\";\n//   <entry.Content components={{ ...defaultComponents, h2: MyH2 }} />\n//\n// Each component is a thin passthrough mirroring its zudo-doc counterpart\n// (e.g. `ContentParagraph` → `<p {...rest}>{children}</p>`). v0 ships the\n// passthroughs unstyled; layering smart-break / heading-anchor / link-icon\n// behaviour on top is independent follow-up — keeping the v0 deliverable\n// focused on infrastructure (issue #33).\n//\n// **`h1` is deliberately not in the map** — page titles render `<h1>` from\n// frontmatter, per the zudo-doc convention. Adding `h1` here would silently\n// double-render the page title.\n//\n// **Each override is exported as a named const AND included in\n// `defaultComponents`** so consumers can tree-shake-import a single component\n// (`import { ContentLink } from \"zfb\"`) without dragging in the whole map.\n//\n// Implementation note: components return the structural JSX-element shape\n// directly — same pattern as `Island`. This keeps the package\n// JSX-runtime-agnostic so it works under either Preact or React without\n// importing a runtime. Both `jsx-runtime` implementations accept the\n// `{ type, props, key }` object on either side of the boundary.\n// ---------------------------------------------------------------------------\n\n/**\n * Public JSX-element shape returned by every override in [`defaultComponents`].\n *\n * Mirrors [`ContentElement`] and [`IslandElement`]: a structural alias for\n * `JSX.Element` so consumers can drop these overrides into both React and\n * Preact JSX without per-framework type setup.\n */\nexport type ContentComponentElement = {\n  readonly type: string;\n  readonly props: Readonly<Record<string, unknown>>;\n  readonly key: unknown;\n};\n\n/**\n * Props accepted by every default override. `children` and any extra\n * attributes (`className`, `id`, `href`, …) are passed through verbatim\n * to the underlying HTML element.\n */\nexport interface ContentComponentProps {\n  children?: VNode;\n  [key: string]: unknown;\n}\n\n/** Internal helper: build a structural JSX element of the given tag. */\nfunction buildOverrideElement(tag: string, props: ContentComponentProps): ContentComponentElement {\n  const { children, ...rest } = props;\n  // Minted through the per-project JSX runtime (`mintElement`) so the\n  // override is a real element under both React and Preact — see the\n  // helper's docblock (zudo-doc#505; React error #31 rationale).\n  return mintElement(tag, { ...rest, children }) as unknown as ContentComponentElement;\n}\n\n/**\n * `<h2>` passthrough override. Ported from zudo-doc's `HeadingH2`, stripped\n * of styling — v0 ships pass-through behaviour; visual treatment is layered\n * on by the consumer (or by a follow-up enhancement pass).\n */\nexport function ContentH2(props: ContentComponentProps): ContentComponentElement {\n  return buildOverrideElement(\"h2\", props);\n}\n\n/** `<h3>` passthrough override. See [`ContentH2`] for the contract. */\nexport function ContentH3(props: ContentComponentProps): ContentComponentElement {\n  return buildOverrideElement(\"h3\", props);\n}\n\n/** `<h4>` passthrough override. See [`ContentH2`] for the contract. */\nexport function ContentH4(props: ContentComponentProps): ContentComponentElement {\n  return buildOverrideElement(\"h4\", props);\n}\n\n/** `<p>` passthrough override. Mirrors zudo-doc's `ContentParagraph`. */\nexport function ContentParagraph(props: ContentComponentProps): ContentComponentElement {\n  return buildOverrideElement(\"p\", props);\n}\n\n/** `<a>` passthrough override. Mirrors zudo-doc's `ContentLink`. */\nexport function ContentLink(props: ContentComponentProps): ContentComponentElement {\n  return buildOverrideElement(\"a\", props);\n}\n\n/** `<strong>` passthrough override. Mirrors zudo-doc's `ContentStrong`. */\nexport function ContentStrong(props: ContentComponentProps): ContentComponentElement {\n  return buildOverrideElement(\"strong\", props);\n}\n\n/** `<blockquote>` passthrough override. Mirrors zudo-doc's `ContentBlockquote`. */\nexport function ContentBlockquote(props: ContentComponentProps): ContentComponentElement {\n  return buildOverrideElement(\"blockquote\", props);\n}\n\n/** `<ul>` passthrough override. Mirrors zudo-doc's `ContentUl`. */\nexport function ContentUl(props: ContentComponentProps): ContentComponentElement {\n  return buildOverrideElement(\"ul\", props);\n}\n\n/** `<ol>` passthrough override. Mirrors zudo-doc's `ContentOl`. */\nexport function ContentOl(props: ContentComponentProps): ContentComponentElement {\n  return buildOverrideElement(\"ol\", props);\n}\n\n/** `<table>` passthrough override. Mirrors zudo-doc's `ContentTable`. */\nexport function ContentTable(props: ContentComponentProps): ContentComponentElement {\n  return buildOverrideElement(\"table\", props);\n}\n\n/** `<code>` passthrough override. Mirrors zudo-doc's `ContentCode`. */\nexport function ContentCode(props: ContentComponentProps): ContentComponentElement {\n  return buildOverrideElement(\"code\", props);\n}\n\n/**\n * Default per-element override map — eleven entries covering the markdown\n * tags the zudo-doc convention overrides (`h2`, `h3`, `h4`, `p`, `a`,\n * `strong`, `blockquote`, `ul`, `ol`, `table`, `code`).\n *\n * `h1` is intentionally absent: page titles render from frontmatter, per\n * the zudo-doc convention.\n *\n * Spread into a `components` prop to compose with custom overrides:\n *\n * ```tsx\n * import { defaultComponents } from \"zfb\";\n *\n * <entry.Content components={{ ...defaultComponents, h2: MyFancyH2 }} />\n * ```\n */\nexport const defaultComponents = {\n  h2: ContentH2,\n  h3: ContentH3,\n  h4: ContentH4,\n  p: ContentParagraph,\n  a: ContentLink,\n  strong: ContentStrong,\n  blockquote: ContentBlockquote,\n  ul: ContentUl,\n  ol: ContentOl,\n  table: ContentTable,\n  code: ContentCode,\n} as const;\n\n/**\n * Merge component maps with the documented precedence order:\n * built-in `defaultComponents` → global slot (`globalThis.__zfb?.mdxComponents`)\n * → per-call `props.components`.\n *\n * Spread in stable key order so the resulting map is deterministic; later\n * entries in the spread win on collision (lowest → highest priority). Absent\n * layers (`undefined`) are no-ops via spread-of-undefined.\n *\n * **Output-neutral by design:** `defaultComponents` entries are pure\n * passthroughs (e.g. `ContentH2` → `<h2>{...props}</h2>`), so introducing\n * this merge into `buildContentComponent` does not change the rendered output.\n */\nexport function mergeMdxComponents(\n  globalSlot: MdxComponents | undefined,\n  perCall: MdxComponents | undefined,\n): MdxComponents {\n  return { ...defaultComponents, ...globalSlot, ...perCall };\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@takazudo/zfb",
-  "version": "2.5.2",
+  "version": "2.6.0",
   "private": false,
   "type": "module",
   "description": "Rust-built static-site engine for Astro and Next.js users — millisecond rebuilds, single binary. SDK with islands, content collections, pagination, and config helpers.",
@@ -74,11 +74,11 @@
     "LICENSE"
   ],
   "optionalDependencies": {
-    "@takazudo/zfb-darwin-arm64": "2.5.2",
-    "@takazudo/zfb-darwin-x64": "2.5.2",
-    "@takazudo/zfb-linux-arm64-gnu": "2.5.2",
-    "@takazudo/zfb-linux-x64-gnu": "2.5.2",
-    "@takazudo/zfb-win32-x64-msvc": "2.5.2"
+    "@takazudo/zfb-darwin-arm64": "2.6.0",
+    "@takazudo/zfb-darwin-x64": "2.6.0",
+    "@takazudo/zfb-linux-arm64-gnu": "2.6.0",
+    "@takazudo/zfb-linux-x64-gnu": "2.6.0",
+    "@takazudo/zfb-win32-x64-msvc": "2.6.0"
   },
   "publishConfig": {
     "access": "public"
@@ -98,9 +98,12 @@
   "devDependencies": {
     "@types/node": "^22.0.0",
     "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.2.4",
     "happy-dom": "^15.7.4",
     "preact": "^10.29.0",
+    "preact-render-to-string": "^6.6.7",
     "react": "^19.2.3",
+    "react-dom": "19.2.6",
     "typescript": "^5.9.0",
     "vitest": "^2.1.9"
   },