@takazudo/zudo-doc 3.1.0 → 3.3.0

package/dist/z-index-defaults/index.js

@@ -0,0 +1,34 @@
+const defaultZIndexTiers = [
+  // global — default in-flow content (implicit baseline)
+  { name: "content", value: 0 },
+  // local — child promotion inside an isolated parent stacking context
+  { name: "local-1", value: 1 },
+  // local — child promotion inside an isolated parent stacking context
+  { name: "local-2", value: 2 },
+  // local — child promotion inside an isolated parent stacking context
+  { name: "local-3", value: 3 },
+  // global — persistent layout chrome: desktop sidebar, TOC, sidebar-toggle
+  // handle, resizer handle
+  { name: "sidebar", value: 10 },
+  // global — sticky top header (sits above sidebar chrome)
+  { name: "toolbar", value: 20 },
+  // global — header menus, version/language switchers
+  { name: "dropdown", value: 30 },
+  // global — reserved: inline popovers (canonical scale; not yet used)
+  { name: "popover", value: 40 },
+  // global — mobile drawer backdrop, <dialog> ::backdrop
+  { name: "modal-backdrop", value: 50 },
+  // global — mobile sidebar drawer panel, search <dialog>
+  { name: "modal", value: 60 },
+  // global — reserved: transient notifications (canonical scale; not yet used)
+  { name: "toast", value: 70 },
+  // global — reserved: highest steady UI layer, below only the transient drag
+  // tier (canonical scale; not yet used)
+  { name: "tooltip", value: 80 },
+  // global — transient drag affordance: sidebar-resizer ghost line (replaces
+  // the z-9999 anti-pattern)
+  { name: "drag", value: 90 }
+];
+export {
+  defaultZIndexTiers
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@takazudo/zudo-doc",
-  "version": "3.1.0",
+  "version": "3.3.0",
   "type": "module",
   "description": "zudo-doc framework primitives layer that sits on top of zfb's engine — sidebar, theme, TOC, breadcrumb, layouts, head injection, View Transitions, SSR-skip wrappers (per ADR-003).",
   "license": "MIT",
@@ -227,15 +227,23 @@
       "types": "./dist/chrome/index.d.ts",
       "default": "./dist/chrome/index.js"
     },
+    "./chrome-bindings": {
+      "types": "./dist/chrome-bindings.d.ts",
+      "default": "./dist/chrome-bindings.js"
+    },
     "./home-page": {
       "types": "./dist/home-page/index.d.ts",
       "default": "./dist/home-page/index.js"
     },
+    "./theme.css": "./dist/theme.css",
     "./safelist.css": "./dist/safelist.css",
     "./safelist": "./dist/safelist.css",
     "./content.css": "./dist/content.css",
     "./page-loading.css": "./dist/page-loading.css",
     "./features.css": "./dist/features.css",
+    "./tsconfig.base.json": "./tsconfig.base.json",
+    "./zfb-config-shim.d.ts": "./zfb-config-shim.d.ts",
+    "./virtual-modules.d.ts": "./virtual-modules.d.ts",
     "./tags-audit": {
       "types": "./dist/tags-audit.d.ts",
       "default": "./dist/tags-audit.js"
@@ -248,6 +256,10 @@
       "types": "./dist/design-token-panel-bootstrap.d.ts",
       "default": "./dist/design-token-panel-bootstrap.js"
     },
+    "./design-token-panel-config": {
+      "types": "./dist/design-token-panel-config/index.d.ts",
+      "default": "./dist/design-token-panel-config/index.js"
+    },
     "./render-markdown": {
       "types": "./dist/render-markdown/index.d.ts",
       "default": "./dist/render-markdown/index.js"
@@ -316,6 +328,10 @@
       "types": "./dist/ai-chat-modal/index.d.ts",
       "default": "./dist/ai-chat-modal/index.js"
     },
+    "./find-in-page": {
+      "types": "./dist/find-in-page/index.d.ts",
+      "default": "./dist/find-in-page/index.js"
+    },
     "./doc-history": {
       "types": "./dist/doc-history/index.d.ts",
       "default": "./dist/doc-history/index.js"
@@ -531,6 +547,34 @@
     "./sidebar-active-slug": {
       "types": "./dist/sidebar-active-slug/index.d.ts",
       "default": "./dist/sidebar-active-slug/index.js"
+    },
+    "./i18n-defaults": {
+      "types": "./dist/i18n-defaults/index.d.ts",
+      "default": "./dist/i18n-defaults/index.js"
+    },
+    "./color-schemes-defaults": {
+      "types": "./dist/color-schemes-defaults/index.d.ts",
+      "default": "./dist/color-schemes-defaults/index.js"
+    },
+    "./docs-schema": {
+      "types": "./dist/docs-schema/index.d.ts",
+      "default": "./dist/docs-schema/index.js"
+    },
+    "./z-index-defaults": {
+      "types": "./dist/z-index-defaults/index.d.ts",
+      "default": "./dist/z-index-defaults/index.js"
+    },
+    "./frontmatter-preview-defaults": {
+      "types": "./dist/frontmatter-preview-defaults/index.d.ts",
+      "default": "./dist/frontmatter-preview-defaults/index.js"
+    },
+    "./directive-vocabulary-defaults": {
+      "types": "./dist/directive-vocabulary-defaults/index.d.ts",
+      "default": "./dist/directive-vocabulary-defaults/index.js"
+    },
+    "./config": {
+      "types": "./dist/config.d.ts",
+      "default": "./dist/config.js"
     }
   },
   "bin": {
@@ -544,15 +588,18 @@
     "bin",
     "eject",
     "routes-src",
+    "tsconfig.base.json",
+    "zfb-config-shim.d.ts",
+    "virtual-modules.d.ts",
     "README.md",
     "CHANGELOG.md"
   ],
   "peerDependencies": {
     "preact": "^10.29.1",
-    "@takazudo/zfb": "^0.1.0-next.77",
-    "@takazudo/zfb-runtime": "^0.1.0-next.77",
-    "@takazudo/zudo-doc-history-server": "^3.0.0",
-    "@takazudo/zdtp": "^0.4.5",
+    "@takazudo/zfb": "^0.1.0-next.78",
+    "@takazudo/zfb-runtime": "^0.1.0-next.78",
+    "@takazudo/zudo-doc-history-server": "^3.1.0",
+    "@takazudo/zdtp": "^0.4.6",
     "shiki": "^4.0.2",
     "zod": "^4.3.6",
     "katex": "^0.16.0",
@@ -593,9 +640,9 @@
     "typescript": "^5.0.0",
     "vitest": "^4.1.0",
     "zod": "^4.3.6",
-    "@takazudo/zfb": "0.1.0-next.77",
-    "@takazudo/zfb-runtime": "0.1.0-next.77",
-    "@takazudo/zudo-doc-history-server": "3.1.0"
+    "@takazudo/zfb": "0.1.0-next.78",
+    "@takazudo/zfb-runtime": "0.1.0-next.78",
+    "@takazudo/zudo-doc-history-server": "3.3.0"
   },
   "scripts": {
     "build": "tsup && tsc -p tsconfig.build.json",

package/routes-src/_chrome.tsx

@@ -13,8 +13,14 @@
 import { routeCtx } from "./_context.js";
 import { createChrome } from "@takazudo/zudo-doc/chrome";
 import { DocHistory } from "@takazudo/zudo-doc/doc-history";
-import type { ChromeHostBindings } from "@takazudo/zudo-doc/factory-context";
 import type { DocNavNode } from "./_docs-helpers.js";
+// Imported via the BARE published subpath rather than a relative
+// `../chrome-bindings.js`. This file is copied into consumer projects by the
+// routes-src mechanism (`scripts/copy-routes-src.mjs`), which rewrites relative
+// `../` imports to `@takazudo/zudo-doc/*` specifiers so the copy resolves
+// against this package's `dist/`. Writing the bare specifier here directly
+// keeps the source identical to that rewritten output.
+import { defineChromeBindings } from "@takazudo/zudo-doc/chrome-bindings";
 // Host-callables channel (#2501): re-exports `settings.chromeBindingsModule`
 // when the host configured one, else `{}` — see
 // `plugins/routes.ts` and `docs/adr/route-injection-seam.md`
@@ -31,19 +37,35 @@ import { chromeBindings } from "virtual:zudo-doc-chrome-bindings";
 // The import MUST stay static — a dynamic/type-only import stops zfb's island
 // scanner from walking it. SSR output is unchanged: `DocHistoryArea` gates on
 // `settings.docHistory` and the island is skip-SSR, so binding the real component
-// vs the stub is byte-identical. Mirrors the host's `pages/lib/_chrome.ts`.
+// vs the stub is byte-identical. Mirrors the host's `src/chrome-bindings.tsx`.
 // (The narrow real-island props signature isn't assignable to the structural
-// `FactoryComponent`, so cast — same as the host.)
+// `FactoryComponent`, so it's widened through `defineChromeBindings` — same
+// helper the host uses — which checks `DocHistory` against its real call-side
+// prop contract before performing the widening, restoring the #2674
+// drift-detection check a bare cast would erase.)
 //
-// `...chromeBindings` is spread AFTER the `DocHistory` default so a host that
-// configured `chromeBindingsModule` can override ANY slot — including
-// DocHistory itself — while a host that didn't still gets the #2480 fix for
-// free. Note the SSR-presentational-only limitation: a client island defined
+// `...chromeBindings` is spread AFTER the `defineChromeBindings({ DocHistory })`
+// result so a host that configured `chromeBindingsModule` can override ANY
+// slot — including DocHistory itself — while a host that didn't still gets
+// the #2480 fix for free. `chromeBindings` (the virtual re-export) is already
+// erased to the structural `ChromeHostBindings` at its own source, so it is
+// spread as-is rather than run back through `defineChromeBindings` (which
+// cannot recover types `defineChromeBindings` never checked in the first
+// place). Note the SSR-presentational-only limitation: a client island defined
 // INSIDE the bindings module is not guaranteed to register on injected routes
 // the way the static `DocHistory` import above is (the virtual re-export sits
 // outside zfb's static-import scanner reachability graph) — see the ADR.
+//
+// `DesignTokenPanelBootstrap` (#2658) is NOT threaded here: unlike DocHistory
+// (whose derive-level default is a no-op stub), the package-default island IS
+// the derive-level default (`chrome/derive.tsx`'s `deriveBodyEndIslands`,
+// gate-2 fix from the Wave-5 confirm #2659) — so this shim, the locked-manifest
+// self-contained doc stub (#2653), and every other bare `createChrome` caller
+// all get it without explicit wiring. Scanner reachability holds through the
+// static chain route → this shim → `createChrome` → `chrome/derive` →
+// `design-token-panel-bootstrap`.
 const chrome = createChrome(routeCtx, {
-  DocHistory: DocHistory as unknown as ChromeHostBindings["DocHistory"],
+  ...defineChromeBindings({ DocHistory }),
   ...chromeBindings,
 });
 

package/routes-src/_virtual.d.ts

@@ -6,6 +6,20 @@
 // The payload is SERIALIZABLE DATA ONLY (ADR Decision 1): `settings`,
 // `translations`, `tagVocabulary`, `colorSchemes`. `_context.ts` narrows it
 // to the concrete `RouteContextPayload` at the seam.
+//
+// SINGLE SOURCE OF TRUTH for three shipped copies (#2656) — edit HERE only:
+//   1. This file itself — typechecks the package's own `src/routes/*.tsx`.
+//   2. `routes-src/_virtual.d.ts` — copied by `scripts/copy-routes-src.mjs`
+//      for downstream `packageOwnedRoutes` consumers.
+//   3. `<package root>/virtual-modules.d.ts` — GENERATED by
+//      `scripts/copy-virtual-modules.mjs` (tsup onSuccess; gitignored like
+//      `routes-src/`), shipped via `tsconfig.base.json`'s `files` so a HOST
+//      project that imports these virtual modules directly (e.g. a `pages/`
+//      re-export stub calling `createRouteContext(routeContext)`) typechecks.
+// Both copy steps rewrite parent-relative `import(...)` specifiers to bare
+// `@takazudo/zudo-doc/*` subpaths, so the relative specifier below stays
+// correct here while the shipped copies resolve from a consumer's
+// node_modules.
 declare module "virtual:zudo-doc-route-context" {
   export const routeContext: {
     settings: unknown;
@@ -27,8 +41,26 @@ declare module "virtual:zudo-doc-route-context" {
 // chromeBindingsModule").
 //
 // Typed via an INLINE `import(...)` type (not a top-level import, which would
-// break this file's ambient module declarations) — see
-// `../factory-context/index.js` for the `ChromeHostBindings` shape.
+// break this file's ambient module declarations) — see the package's
+// factory-context module (`src/factory-context/index.ts`) for the
+// `ChromeHostBindings` shape.
 declare module "virtual:zudo-doc-chrome-bindings" {
   export const chromeBindings: import("@takazudo/zudo-doc/factory-context").ChromeHostBindings;
 }
+
+// Ambient typing for the design-token-panel-config virtual module emitted by
+// the routes plugin (`addVirtualModule("virtual:zudo-doc-design-token-panel-config",
+// …)`, #2658). No on-disk source — materialised at build, either as a
+// re-export of the host's `settings.designTokenPanelConfigModule` file or as
+// a re-export of the package default (`@takazudo/zudo-doc/design-token-panel-config`)
+// when the setting is absent. See `plugins/routes.ts` and this package's
+// `design-token-panel-bootstrap.tsx` for the full contract.
+//
+// Typed via an inline `import(...)` type (not a top-level import, for the
+// same ambient-module-declaration reason as `chromeBindings` above) — see
+// `@takazudo/zdtp`'s `PanelConfig`.
+declare module "virtual:zudo-doc-design-token-panel-config" {
+  export const buildDesignTokenPanelConfig: (
+    mode: "light" | "dark",
+  ) => import("@takazudo/zdtp").PanelConfig;
+}

package/tsconfig.base.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "allowImportingTsExtensions": true,
+    "resolveJsonModule": true,
+    "verbatimModuleSyntax": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "forceConsistentCasingInFileNames": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "allowJs": true,
+    "jsx": "preserve",
+    "strict": true,
+    "noImplicitAny": true,
+    "strictNullChecks": true,
+    "strictFunctionTypes": true,
+    "strictBindCallApply": true,
+    "strictPropertyInitialization": true,
+    "noImplicitThis": true,
+    "useUnknownInCatchVariables": true,
+    "alwaysStrict": true,
+    "baseUrl": "."
+  },
+  "files": ["./zfb-config-shim.d.ts", "./virtual-modules.d.ts"]
+}

package/virtual-modules.d.ts

@@ -0,0 +1,79 @@
+// GENERATED FILE — DO NOT EDIT.
+// Built from src/routes/_virtual.d.ts by scripts/copy-virtual-modules.mjs
+// (tsup onSuccess), with parent-relative import(...) type specifiers
+// rewritten to bare @takazudo/zudo-doc/* subpaths. Edit the source file and
+// rebuild the package (pnpm --filter @takazudo/zudo-doc build) instead.
+//
+// Host-facing: pulled into consumer projects via tsconfig.base.json's
+// top-level "files" so host code importing the zfb virtual modules
+// (virtual:zudo-doc-route-context / virtual:zudo-doc-chrome-bindings)
+// typechecks. Consumer-level regression proof (tsc/zfb check against a
+// fixture extending tsconfig.base.json) lives in the Wave-5 confirm case
+// (zudolab/zudo-doc#2659).
+
+// Ambient typing for the route-context virtual module emitted by the routes
+// plugin (`addVirtualModule("virtual:zudo-doc-route-context", …)`). The module
+// has no on-disk source — it is materialised at build by the zfb plugin runtime
+// — so this declaration gives the package route entrypoints a typed import.
+//
+// The payload is SERIALIZABLE DATA ONLY (ADR Decision 1): `settings`,
+// `translations`, `tagVocabulary`, `colorSchemes`. `_context.ts` narrows it
+// to the concrete `RouteContextPayload` at the seam.
+//
+// SINGLE SOURCE OF TRUTH for three shipped copies (#2656) — edit HERE only:
+//   1. This file itself — typechecks the package's own `src/routes/*.tsx`.
+//   2. `routes-src/_virtual.d.ts` — copied by `scripts/copy-routes-src.mjs`
+//      for downstream `packageOwnedRoutes` consumers.
+//   3. `<package root>/virtual-modules.d.ts` — GENERATED by
+//      `scripts/copy-virtual-modules.mjs` (tsup onSuccess; gitignored like
+//      `routes-src/`), shipped via `tsconfig.base.json`'s `files` so a HOST
+//      project that imports these virtual modules directly (e.g. a `pages/`
+//      re-export stub calling `createRouteContext(routeContext)`) typechecks.
+// Both copy steps rewrite parent-relative `import(...)` specifiers to bare
+// `@takazudo/zudo-doc/*` subpaths, so the relative specifier below stays
+// correct here while the shipped copies resolve from a consumer's
+// node_modules.
+declare module "virtual:zudo-doc-route-context" {
+  export const routeContext: {
+    settings: unknown;
+    translations: Record<string, Record<string, string>>;
+    tagVocabulary: ReadonlyArray<Record<string, unknown>>;
+    /** Host color-scheme palette map. `null` when the caller did not pass
+     *  `colorSchemes` to `zudoDocPreset` — `_chrome.tsx` falls back to
+     *  `DEFAULT_SCHEME` in that case. */
+    colorSchemes: Record<string, unknown> | null;
+  };
+}
+
+// Ambient typing for the chrome-bindings virtual module emitted by the routes
+// plugin (`addVirtualModule("virtual:zudo-doc-chrome-bindings", …)`, #2501).
+// No on-disk source — materialised at build, either as a re-export of the
+// host's `settings.chromeBindingsModule` file or as an empty-object fallback
+// when the setting is absent. See `plugins/routes.ts` and
+// `docs/adr/route-injection-seam.md` ("Host-callables channel —
+// chromeBindingsModule").
+//
+// Typed via an INLINE `import(...)` type (not a top-level import, which would
+// break this file's ambient module declarations) — see the package's
+// factory-context module (`src/factory-context/index.ts`) for the
+// `ChromeHostBindings` shape.
+declare module "virtual:zudo-doc-chrome-bindings" {
+  export const chromeBindings: import("@takazudo/zudo-doc/factory-context").ChromeHostBindings;
+}
+
+// Ambient typing for the design-token-panel-config virtual module emitted by
+// the routes plugin (`addVirtualModule("virtual:zudo-doc-design-token-panel-config",
+// …)`, #2658). No on-disk source — materialised at build, either as a
+// re-export of the host's `settings.designTokenPanelConfigModule` file or as
+// a re-export of the package default (`@takazudo/zudo-doc/design-token-panel-config`)
+// when the setting is absent. See `plugins/routes.ts` and this package's
+// `design-token-panel-bootstrap.tsx` for the full contract.
+//
+// Typed via an inline `import(...)` type (not a top-level import, for the
+// same ambient-module-declaration reason as `chromeBindings` above) — see
+// `@takazudo/zdtp`'s `PanelConfig`.
+declare module "virtual:zudo-doc-design-token-panel-config" {
+  export const buildDesignTokenPanelConfig: (
+    mode: "light" | "dark",
+  ) => import("@takazudo/zdtp").PanelConfig;
+}

package/zfb-config-shim.d.ts

@@ -0,0 +1,188 @@
+// Package-shipped type shim for the bare `zfb/config` specifier (#2656).
+//
+// `@takazudo/zfb` is consumed as a published npm package. The package
+// exposes its real config types under the *scoped* subpath
+// `@takazudo/zfb/config` → `dist/config.d.ts`. But `zfb.config.ts` imports
+// from the *bare* specifier `zfb/config`, which zfb's build tool aliases to
+// a runtime-only stub at parse time (`zfb-config-stub.mjs` — `defineConfig`
+// is identity, carrying no types). No real file backs `zfb/config` in
+// `node_modules`, so this ambient declaration is what supplies the
+// `ZfbConfig` type to `zfb.config.ts`.
+//
+// Pulled into a consuming project via `tsconfig.base.json`'s
+// `files: ["./zfb-config-shim.d.ts", "./virtual-modules.d.ts"]` — a project
+// extending the base no longer needs its own local `zfb-shim.d.ts`.
+//
+// IMPORTANT — this block is the source of truth for the type `zfb check`
+// (plain `tsc --noEmit`) binds against the config. An ambient `declare
+// module` wins over node resolution AND over tsconfig `paths`, so it must
+// be kept in sync BY HAND with the published `@takazudo/zfb/config`
+// (`dist/config.d.ts`). When it lags the engine, valid config fields fail
+// `pnpm check` with TS2353 (see Takazudo/zudo-front-builder#678 +
+// zudolab/zudo-doc#1834 — `bundle` was missing here, blocking next.22's
+// `bundle.exclude`). See `packages/zudo-doc/CLAUDE.md` ("Shipped ambient
+// type shims") for the hand-sync duty this file carries.
+
+declare module "zfb/config" {
+  /** JSX framework runtime. */
+  export type Framework = "preact" | "react";
+
+  /** A content collection registered with the zfb engine. */
+  export interface CollectionDef {
+    /** Identifier used at the call site (e.g. `"docs"`). */
+    name: string;
+    /** Directory (relative to the project root) holding the entries. */
+    path: string;
+    /**
+     * Optional schema. Reserved for v1.1 — accepted but not enforced
+     * today. Authored as zod and converted to JSON Schema via
+     * `z.toJSONSchema()` at the boundary.
+     */
+    schema?: Record<string, unknown>;
+  }
+
+  /** Tailwind options; absent = defaults. */
+  export interface TailwindConfig {
+    enabled?: boolean;
+  }
+
+  /** User-supplied plugin configuration entry. */
+  export interface PluginConfig {
+    name: string;
+    options?: Record<string, unknown>;
+  }
+
+  /**
+   * Bundler options. Mirrors `BundleConfig` in crates/zfb/src/config.rs
+   * and the published `@takazudo/zfb/config` (`dist/config.d.ts`). Added
+   * in next.22 (`bundle.exclude`, #664) and extended in next.23
+   * (`mainFields` / `external`, #676).
+   */
+  export interface BundleConfig {
+    /**
+     * Project-relative, gitignore-style globs for source files the bundler
+     * must NOT pull into the esbuild graph (e.g. test fixtures or
+     * `*.stories.tsx`). Matched files are skipped from the shadow-tree walk
+     * and dropped from any eager `import.meta.glob(...)` expansion.
+     */
+    exclude?: string[];
+    /**
+     * Explicit esbuild `main-fields` for the `--platform=neutral` page/SSR
+     * pass (empty by default under `neutral`), letting CJS-`main`-only deps
+     * resolve. Mirrors `BundleConfig::main_fields`.
+     */
+    mainFields?: string[];
+    /**
+     * Bare specifiers to mark external in the `--platform=neutral` pass so
+     * esbuild leaves them unbundled. Mirrors `BundleConfig::external`.
+     */
+    external?: string[];
+  }
+
+  /** Mirrors the Rust `Config` struct one-for-one. */
+  export interface ZfbConfig {
+    outDir?: string;
+    publicDir?: string;
+    host?: string;
+    port?: number;
+    framework?: Framework;
+    collections?: CollectionDef[];
+    tailwind?: TailwindConfig;
+    /**
+     * Bundler options. `bundle.exclude` keeps project-relative globs out of
+     * the esbuild graph — used e.g. to skip `e2e/fixtures/**` so the MDX link
+     * resolver doesn't walk committed test-fixture trees (silences spurious
+     * broken-link warnings). Mirrors `Config::bundle`.
+     */
+    bundle?: BundleConfig;
+    plugins?: PluginConfig[];
+    adapter?: string;
+    /**
+     * Strip `.md` / `.mdx` from in-page `<a href>` paths and append a
+     * trailing `/` so author-written `[label](other.mdx)` references
+     * resolve to the rendered route URL. Mirrors Config::strip_md_ext
+     * in crates/zfb/src/config.rs (zudolab/zfb#131).
+     */
+    stripMdExt?: boolean;
+    /**
+     * Site base path. Prefixed onto stable HTML asset URLs (CSS / JS
+     * `<link>` and `<script>` tags). Normalised to start AND end with
+     * `/`; `undefined` / `""` / `"/"` all behave identically (no
+     * prefix). Mirrors Config::base in crates/zfb/src/config.rs
+     * (Takazudo/zudo-front-builder#154).
+     */
+    base?: string;
+    /**
+     * Configures the syntect-based syntax highlighter shipped with zfb.
+     * Mirrors `CodeHighlightConfig` / `code_highlight` in crates/zfb/src/config.rs
+     * (single-theme: Takazudo/zudo-front-builder#188 / sub #194, commit 339e30f;
+     * dual-theme themeLight/themeDark added in the follow-up shipped in
+     * zfb 0.1.0-next.45+).
+     * When omitted, the engine falls back to the hardcoded default theme `base16-ocean.dark`.
+     *
+     * Single-theme mode: set `theme` — tokens get inline `style="color:#hex"`.
+     * Dual-theme mode: set BOTH `themeLight` and `themeDark` (mutually exclusive
+     * with `theme`) — tokens get `--shiki-light`/`--shiki-dark` CSS custom
+     * properties and the `<pre>` gains `class="syntect-dual"` + `--shiki-*-bg`.
+     * All names are SYNTECT theme names, not Shiki names.
+     */
+    codeHighlight?: {
+      theme?: string;
+      themesDir?: string;
+      themeLight?: string;
+      themeDark?: string;
+    };
+    /**
+     * Markdown link resolver (port of `remarkResolveMarkdownLinks`).
+     * Mirrors `Config::resolve_markdown_links` in crates/zfb/src/config.rs
+     * (Takazudo/zudo-front-builder PR #234 / zudolab/zudo-doc#1577).
+     * When `enabled: true`, the build appends `ResolveLinksPlugin` to the
+     * mdast pipeline so author-written `[label](./other.mdx)` links are
+     * rewritten to the corresponding rendered route URL — bypassing the
+     * file→directory transformation that breaks relative paths in dist
+     * HTML when `foo.mdx` becomes `foo/index.html`.
+     */
+    resolveMarkdownLinks?: {
+      enabled?: boolean;
+      docsDir?: string;
+      dirs?: Array<{ dir: string; routePrefix: string }>;
+      onBrokenLinks?: "warn" | "error" | "ignore";
+    };
+    /**
+     * Whether the basePath rewriter should append a trailing `/` to
+     * extensionless absolute hrefs. Mirrors `Config::trailing_slash` in
+     * crates/zfb/src/config.rs (Takazudo/zudo-front-builder PR #234 /
+     * zudolab/zudo-doc#1579). Off by default — preserves byte-for-byte
+     * parity with the pre-`trailingSlash` build for projects that
+     * haven't opted in.
+     */
+    trailingSlash?: boolean;
+    /**
+     * Minify production HTML output from `zfb build`.
+     * Mirrors `Config::minify_html` in crates/zfb/src/config.rs.
+     */
+    minifyHtml?: boolean;
+    /**
+     * Markdown / MDX pipeline options. Mirrors `Config::markdown` →
+     * `MarkdownConfig` in crates/zfb/src/config.rs. zfb next.12 moved the
+     * former-Core features under `markdown.features` and next.13 ships the
+     * rest as opt-in; zudo-doc uses `markdown.features` to opt back into the
+     * former-Core four plus the additional opt-in features (#1804). Each
+     * `features` value is per-feature: `true` for boolean-shorthand features,
+     * or an options object for object-typed features.
+     */
+    markdown?: {
+      gfm?: boolean | Record<string, boolean>;
+      toc?: Record<string, unknown>;
+      externalLinks?: Record<string, unknown>;
+      cjkFriendly?: boolean;
+      features?: Record<string, boolean | Record<string, unknown>>;
+    };
+  }
+
+  /**
+   * Identity helper: returns the supplied config as-is, but typed
+   * against `ZfbConfig`. Use as the default export of `zfb.config.ts`.
+   */
+  export function defineConfig(config: ZfbConfig): ZfbConfig;
+}