@takazudo/zudo-doc 3.2.0 → 3.3.0

package/CHANGELOG.md

@@ -4,6 +4,35 @@ All notable changes to `@takazudo/zudo-doc` are documented in this file.
 
 The format is based on Keep a Changelog, and release notes are generated from the changelog MDX pages.
 
+## [3.3.0] - 2026-07-12
+
+### Features
+
+- **Minimal Scaffold (epic #2651).** `create-zudo-doc` now emits a locked ~12-file minimal manifest — a generated project is one config file (`zfb.config.ts` using the diff-from-defaults `zudoDoc({...})`) plus Markdown content, extended via eject. The package now owns the defaults that were previously copied into every scaffold: default `@theme` tokens ship as `@takazudo/zudo-doc/theme.css`, and i18n, color schemes, docs schema, z-index, frontmatter-preview, and directives ship as package-default data modules. (98a56931, 257fa9aa, 5f45bf15, 2056824f)
+- Added the `zudoDoc()` single-entry config API returning a full `ZfbConfig`; the showcase and generated scaffolds migrate their `zfb.config.ts` and the four doc-route stubs to the self-contained form. (a06f5990, 1fc470f0, 6e4a6d08)
+- Added the `defineChromeBindings` widening adapter — a typed helper that replaces chrome-binding casts; the generator now injects it instead of a `DocHistory` cast. (5915707b, aa29e479, 0e49a6ad)
+- Absorbed the Tauri find-in-page island (Cmd/Ctrl+F find bar) into `@takazudo/zudo-doc/find-in-page`, mounted from the package's body-end islands behind a new `findInPage` setting (default `false`). The island self-gates on `window.__TAURI_INTERNALS__`, so it stays a safe no-op outside a Tauri shell. `create-zudo-doc`'s tauri feature now emits `findInPage: true` for generated Tauri scaffolds. (97885c5d, cc1bc846, f5e4c953)
+- Added a package-owned `DesignTokenPanelBootstrap` island, mounted from the package's routes. (5f75a9ed, 105a3b40)
+- The package now ships `tsconfig.base`, a `zfb-config` shim, and generated virtual-module types. (3de2b209)
+
+### Bug Fixes
+
+- Corrected the `create-zudo-doc` Node engine floor and documented the built-in MDX components (#2702, #2703). (edf5cc4f)
+- Exported the `./find-in-page` subpath so hosts can mount `FindInPageInit`. (a4c4f8e5)
+- Stopped the generator dropping unlisted config keys and guarded `DEFAULT_MIRROR` drift. (ac0c6afa)
+- The i18n locale doc stub now threads `isFallback` and a per-locale content directory. (8355e537)
+- Routed package-manager script commands through a single `pmRunCommand` helper. (cb88bde6)
+- Made the `pages` typecheck project Preact-native. (a24dfef4)
+- Warn on a missing color scheme, and clarified the `zudoDoc` shallow-merge docs. (8f913319)
+- Tightened `frontmatterRenderers`/`buildFrontmatterPreviewEntries` slot types so drift is detected for real. (d9d9b828)
+- Fixed the default header chrome background. (f0245086)
+
+### Other Changes
+
+- Retired `packages/md-plugins` and dropped the showcase Design Token Panel config copy in favor of the package default. (e99ebe7d, c74c481a)
+- Patched transitive security advisories via pnpm overrides and bumped `@takazudo/zdtp` 0.4.5 → 0.4.6. (24013cd1, 731c8677)
+- Rewrote the core structure docs for the minimal→extend model (EN + JA). (f57d092e)
+
 ## [3.2.0] - 2026-07-08
 
 ### Features

package/dist/chrome/derive.d.ts

@@ -47,7 +47,13 @@ export declare function deriveSearchWidgetSlot(ctx: ChromeContext): (props: {
     noResultsText: string;
 }) => JSX.Element;
 /** Derive the body-end islands: `ctx.hostBindings.BodyEndIslands` when supplied,
- *  else the package-island subset reconstructed from `settings`. */
+ *  else the package-island subset reconstructed from `settings`. The design-
+ *  token-panel bootstrap slot defaults to the PACKAGE-DEFAULT
+ *  `DesignTokenPanelBootstrap` island (statically imported above — #2658
+ *  gate-2 fix, Wave-5 confirm #2659) so a bare `createChrome(routeCtx)` call
+ *  (the locked-manifest self-contained doc stub, #2653) still mounts the
+ *  settings-gated panel; `ctx.hostBindings.DesignTokenPanelBootstrap`
+ *  overrides it when a host supplies its own. */
 export declare function deriveBodyEndIslands(ctx: ChromeContext): ReturnType<typeof createBodyEndIslands>;
 /** Derive the DocHistory island: `ctx.hostBindings.DocHistory` when supplied,
  *  else the package no-op stub. */

package/dist/chrome/derive.js

@@ -6,6 +6,7 @@ import {
   SEMANTIC_RAMP_DEFAULTS
 } from "../color-scheme-utils.js";
 import { createBodyEndIslands } from "../doc-body-end-islands/index.js";
+import { DesignTokenPanelBootstrap } from "../design-token-panel-bootstrap.js";
 import { SearchWidget } from "../search-widget/index.js";
 import { createMdxComponents } from "../mdx-components/index.js";
 import { createCategoryNavWrapper } from "../category-nav/index.js";
@@ -64,7 +65,14 @@ function deriveComposeMetaTitle(ctx) {
 }
 function resolveHostScheme(ctx, key) {
   if (!ctx.colorSchemes) return DEFAULT_SCHEME;
-  return ctx.colorSchemes[key] ?? DEFAULT_SCHEME;
+  const scheme = ctx.colorSchemes[key];
+  if (!scheme) {
+    console.warn(
+      `[zudo-doc] color scheme "${key}" not found in the configured colorSchemes \u2014 falling back to the neutral default scheme. Available schemes: ${Object.keys(ctx.colorSchemes).join(", ") || "(none)"}`
+    );
+    return DEFAULT_SCHEME;
+  }
+  return scheme;
 }
 function deriveColorSchemeGenerators(ctx) {
   return {
@@ -139,7 +147,10 @@ function deriveSearchWidgetSlot(ctx) {
   return ctx.hostBindings.SearchWidget ?? SearchWidgetBound;
 }
 function deriveBodyEndIslands(ctx) {
-  return ctx.hostBindings.BodyEndIslands ?? createBodyEndIslands({ settings: ctx.settings });
+  return ctx.hostBindings.BodyEndIslands ?? createBodyEndIslands({
+    settings: ctx.settings,
+    DesignTokenPanelBootstrap: ctx.hostBindings.DesignTokenPanelBootstrap ?? DesignTokenPanelBootstrap
+  });
 }
 function deriveDocHistorySlot(ctx) {
   return ctx.hostBindings.DocHistory ?? DocHistoryStub;

package/dist/chrome-bindings.d.ts

@@ -0,0 +1,159 @@
+import type { ChromeHostBindings } from "./factory-context/index.js";
+/**
+ * Props the header passes to the `SearchWidget` slot — the 7 locale-aware
+ * strings from `header-with-defaults`'s `<SearchWidget … />` render (via
+ * `deriveSearchWidgetSlot`'s `SearchWidgetBound`, `chrome/derive.tsx`). NOTE
+ * the package's own `SearchWidget` also takes `base`, but the chrome binds that
+ * internally — a host-supplied widget is called with these 7 props ONLY, so
+ * requiring `base` here would (correctly) be drift.
+ */
+export interface SearchWidgetSlotProps {
+    placeholderText: string;
+    shortcutHint: string;
+    resultCountTemplate: string;
+    searchLabel: string;
+    searchUnavailableText: string;
+    loadingIndexText: string;
+    noResultsText: string;
+}
+/**
+ * Props the chrome passes to the `BodyEndIslands` slot — matches
+ * `BodyEndIslandsProps` (`doc-body-end-islands`); called as
+ * `<BodyEndIslands basePath={…} />` in `home-page` / `doc-body-end`.
+ */
+export interface BodyEndIslandsSlotProps {
+    basePath: string;
+    aiChatBodyLabel?: string;
+}
+/**
+ * Props the chrome passes to the `DocHistory` island slot — matches
+ * `DocHistoryProps` (`doc-history/index.tsx`) / `DocHistoryComponent`
+ * (`doc-history-area`), rendered as
+ * `<DocHistory slug=… locale=… basePath=… />`.
+ */
+export interface DocHistorySlotProps {
+    slug: string;
+    locale?: string;
+    basePath?: string;
+}
+/**
+ * Props the chrome passes to the `DesignTokenPanelBootstrap` slot — NONE. It is
+ * rendered as `<DesignTokenPanelBootstrap />` (zero props) inside
+ * `createBodyEndIslands`. An empty object type (no index signature) so a
+ * zero-prop or all-optional-prop component is accepted while a component that
+ * REQUIRES any prop is drift.
+ */
+export type DesignTokenPanelBootstrapSlotProps = Record<never, never>;
+/**
+ * One footer tag entry the `loadTagsForLocale` result is read for —
+ * `footer-with-defaults` maps over the array reading `{ tag, count }`. The
+ * return contract is a `readonly` array of these (extra per-entry fields, e.g.
+ * the `docs` on `collectTags`' `TagInfo`, are allowed — a supertype element).
+ */
+export interface FooterTagEntry {
+    tag: string;
+    count: number;
+}
+/**
+ * Props the chrome passes to each `frontmatterRenderers[key]` renderer —
+ * mirrors `FrontmatterCellRendererProps` at the real call site
+ * (`metainfo/frontmatter-preview.tsx`: `rendererFn({ value, entryKey, data,
+ * locale })`). A provided renderer's parameter must be a SUPERTYPE of this (it
+ * may read a subset), so a renderer REQUIRING a prop the chrome never passes is
+ * a compile error — the #2674 drift check this slot would otherwise erase.
+ */
+export interface FrontmatterRendererSlotProps {
+    value: NonNullable<unknown>;
+    entryKey: string;
+    data: Record<string, unknown>;
+    locale?: string;
+}
+/**
+ * The compile-time-checked input for {@link defineChromeBindings}. See the
+ * module header for the drift-detection rationale.
+ */
+export interface ChromeBindingsInput {
+    /** Header search widget — see {@link SearchWidgetSlotProps}. */
+    SearchWidget?: (props: SearchWidgetSlotProps) => unknown;
+    /** Body-end bootstrap islands — see {@link BodyEndIslandsSlotProps}. */
+    BodyEndIslands?: (props: BodyEndIslandsSlotProps) => unknown;
+    /** DocHistory island — see {@link DocHistorySlotProps}. */
+    DocHistory?: (props: DocHistorySlotProps) => unknown;
+    /** Design-token-panel bootstrap island — see {@link DesignTokenPanelBootstrapSlotProps}. */
+    DesignTokenPanelBootstrap?: (props: DesignTokenPanelBootstrapSlotProps) => unknown;
+    /**
+     * Per-page git-history meta manifest (data slot). Read as
+     * `Record<string, DocHistoryMetaEntry>` inside `doc-metainfo-area` /
+     * `doc-history-area`; the loose `Record<string, unknown>` is the boundary shape.
+     */
+    docHistoryMeta?: Record<string, unknown>;
+    /**
+     * Sidebar section config (opaque data blob — the chrome casts it to `never`
+     * before handing it to `buildSidebarForSection`). Typed `object` NOT
+     * `Record<string, unknown>` on purpose: a concrete interface-typed sidebars
+     * object (no index signature) must be accepted WITHOUT a cast.
+     */
+    sidebarsConfig?: object;
+    /** Footer tag vocabulary (data slot); read structurally by `footer-with-defaults`. */
+    tagVocabulary?: readonly unknown[];
+    /**
+     * Frontmatter preview renderers keyed by field (renderer record). Each value
+     * must be callable with {@link FrontmatterRendererSlotProps} (the fixed
+     * package call-side contract), so a non-function or a renderer requiring an
+     * unpassed prop is a compile error. Narrow-props renderers still work
+     * (parameter contravariance). Unlike `mdxExtras`, this slot has a fixed call
+     * site, so it carries the real contract rather than a loose `Record`.
+     */
+    frontmatterRenderers?: Record<string, (props: FrontmatterRendererSlotProps) => unknown>;
+    /**
+     * MDX content-component overrides (renderer record). Same loose value type as
+     * `frontmatterRenderers`; the showcase's `MdxStub = (_props: unknown) => null`
+     * is accepted deliberately (`unknown` props are a safe supertype).
+     */
+    mdxExtras?: Record<string, unknown>;
+    /**
+     * Frontmatter preview entry builder. `doc-content-header` calls it with the
+     * page `data` (`Record<string, unknown>`) and spreads the result into
+     * `<FrontmatterPreview entries={…} />`, which destructures each entry as
+     * `[key, value]` — so the return must be an array of `[string, unknown]`
+     * tuples, not merely an array.
+     */
+    buildFrontmatterPreviewEntries?: (data: Record<string, unknown>) => readonly (readonly [string, unknown])[];
+    /**
+     * Footer tag-list loader. `footer-with-defaults` calls it with the locale and
+     * maps the result reading `{ tag, count }` — see {@link FooterTagEntry}.
+     * A wrong return type (e.g. a non-array) is a compile error.
+     */
+    loadTagsForLocale?: (lang: string) => readonly FooterTagEntry[];
+    /**
+     * Extra content rendered inside the doc content header. An arg-object
+     * RENDERER — the `ChromeHostBindings` type is already call-side-precise, so
+     * reuse it verbatim (no widening friction).
+     */
+    docContentHeaderExtras?: ChromeHostBindings["docContentHeaderExtras"];
+    /**
+     * Extra content rendered in the home hero. An arg-object RENDERER — reuse the
+     * already call-side-precise `ChromeHostBindings` type verbatim.
+     */
+    homeExtras?: ChromeHostBindings["homeExtras"];
+}
+/**
+ * Reject unknown slot names. Generic inference (below) turns OFF the
+ * excess-property check that a plain `input: ChromeBindingsInput` parameter
+ * would get for an object literal, so re-impose it explicitly: any key of `T`
+ * that is NOT a `ChromeBindingsInput` slot is mapped to `never`, making a real
+ * value for it fail to assign.
+ */
+type NoExtraKeys<T> = ChromeBindingsInput & Record<Exclude<keyof T, keyof ChromeBindingsInput>, never>;
+/**
+ * Widen a compile-time-checked host bindings object to `ChromeHostBindings`.
+ *
+ * The generic `T` captures the caller's exact object so {@link NoExtraKeys}
+ * can reject unknown slot names; `T extends ChromeBindingsInput` enforces every
+ * slot's per-call-site contract (a component requiring a prop the chrome never
+ * passes, or a function slot with an incompatible return type, is a COMPILE
+ * ERROR). Runtime behaviour is pure PASS-THROUGH — the returned object IS the
+ * input.
+ */
+export declare function defineChromeBindings<T extends ChromeBindingsInput>(input: T & NoExtraKeys<T>): ChromeHostBindings;
+export {};

package/dist/chrome-bindings.js

@@ -0,0 +1,6 @@
+function defineChromeBindings(input) {
+  return input;
+}
+export {
+  defineChromeBindings
+};

package/dist/color-scheme-utils.d.ts

@@ -115,7 +115,7 @@ export interface TierItem {
  *
  * Always the explicit form (independent of `referencesRamps` declaration
  * order) — see item-id contract in `buildRampTiers`
- * (`src/config/design-token-panel-config.ts`): tier ids `base`/`accent`/`state`,
+ * (`./design-token-panel-config/index.ts`): tier ids `base`/`accent`/`state`,
  * item ids `base-0..4`/`accent-0..2`/`state-{danger,success,warning,info}`.
  */
 export declare function rampRefToPanelDefault(ref: RampRef): string;

package/dist/color-schemes-defaults/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Default color schemes — Default Light + Default Dark.
+ *
+ * Ported verbatim from the `create-zudo-doc` base template's
+ * `src/config/color-schemes.ts` `colorSchemes` export (epic
+ * zudolab/zudo-doc#2651, S4 #2654), so a generated project needs no
+ * color-schemes config file of its own.
+ *
+ * Ramp-native model (Color Ramp Restructure — zudolab/zudo-doc#2584;
+ * minimized to 5/3 in #2602). A `ColorScheme` is `{ ramps, map }` — the
+ * MECHANISM type is owned by `@takazudo/zudo-doc/color-scheme-utils` and is
+ * reused here, not re-declared:
+ *   - `ramps` — the shared Tier-1 source of truth: a warm-neutral `base` ramp
+ *     (5 stops, index 0 = lightest), an `accent` ramp (3 stops), and 4 `state`
+ *     colors. Light and dark modes SHARE these values.
+ *   - `map` — the per-mode Tier-2 wiring: which ramp stop (or literal OKLCH)
+ *     each UI role points at.
+ *
+ * A project's `ZudoDocConfig.colorSchemes` override is merged over this
+ * default by `zudoDoc()` (#2657).
+ */
+import type { ColorScheme } from "../color-scheme-utils.js";
+export declare const defaultColorSchemes: Record<string, ColorScheme>;

package/dist/color-schemes-defaults/index.js

@@ -0,0 +1,121 @@
+const ramps = {
+  base: [
+    "oklch(.965 .004 65)",
+    // 0 — lightest (light bg / dark fg)
+    "oklch(.705 .008 65)",
+    // 1 — dark muted / light selection & mermaid fill
+    "oklch(.480 .008 65)",
+    // 2 — light muted / dark selection & mermaid note
+    "oklch(.300 .006 65)",
+    // 3 — dark codeBg / mermaid fill
+    "oklch(.185 .005 65)"
+    // 4 — darkest (dark bg / light fg)
+  ],
+  accent: [
+    "oklch(.755 .130 64)",
+    // 0 — dark hover (was accent2)
+    "oklch(.700 .158 62)",
+    // 1 — dark accent (was accent3)
+    "oklch(.470 .120 56)"
+    // 2 — light accent (was accent6)
+  ],
+  state: {
+    danger: "oklch(.640 .170 25)",
+    success: "oklch(.680 .145 145)",
+    warning: "oklch(.760 .135 82)",
+    info: "oklch(.680 .130 245)"
+  }
+};
+const darkMap = {
+  bg: { base: 4 },
+  fg: { base: 0 },
+  selectionBg: { base: 2 },
+  selectionFg: { base: 0 },
+  semantic: {
+    // Merged onto bg (b4) — elevated panels read as page-bg + border, no gray fill.
+    surface: { base: 4 },
+    muted: { base: 1 },
+    accent: { accent: 1 },
+    accentHover: { accent: 0 },
+    codeBg: { base: 3 },
+    codeFg: { base: 0 },
+    success: { state: "success" },
+    // Per-mode AA-tuned literal — shared state.danger oklch(.640 .170 25) is too
+    // dark for the danger-admonition title on its 12%-tint dark bg. L .640→.655
+    // (H/C fixed) — admonition-danger at threshold+0.1; carried from #2593.
+    danger: "oklch(.655 .170 25)",
+    warning: { state: "warning" },
+    info: { state: "info" },
+    mermaidNodeBg: { base: 3 },
+    mermaidText: { base: 0 },
+    mermaidLine: { base: 1 },
+    mermaidLabelBg: { base: 3 },
+    mermaidNoteBg: { base: 2 },
+    chatUserBg: { accent: 1 },
+    chatUserText: { base: 4 },
+    // Merged onto bg (b4) — the chat assistant bubble reads as page-bg + border.
+    chatAssistantBg: { base: 4 },
+    chatAssistantText: { base: 0 },
+    imageOverlayBg: { base: 4 },
+    imageOverlayFg: { base: 0 },
+    // Search-result <mark> highlight: an amber (accent-hue) fill with dark text —
+    // the classic highlighter look, identical in both modes. Kept as literals so
+    // the amber fill is scheme-stable; matchedKeywordFg dark so text clears AA on
+    // the amber bg — matched-keyword at threshold+0.1; carried from #2593.
+    matchedKeywordBg: "oklch(.700 .158 62)",
+    matchedKeywordFg: "oklch(.300 .003 65)"
+  }
+};
+const lightMap = {
+  bg: { base: 0 },
+  fg: { base: 4 },
+  selectionBg: { base: 1 },
+  selectionFg: { base: 4 },
+  semantic: {
+    // Merged onto bg (b0) — elevated panels read as page-bg + border, no gray fill.
+    surface: { base: 0 },
+    muted: { base: 2 },
+    accent: { accent: 2 },
+    // Light: per-mode literal — the accent ramp has no stop darker than accent2,
+    // so the link-hover state darkens further (hover-darkens-on-light
+    // convention). L .400, C fitted to the sRGB gamut edge at that L; carried
+    // from #2595. accent-hover-vs-bg clears threshold+0.1.
+    accentHover: "oklch(.400 .096 56)",
+    // Merged onto bg (b0) — inline/code-block fill reads as page-bg + border.
+    codeBg: { base: 0 },
+    codeFg: { base: 4 },
+    // Light: per-mode literals — the shared state colors are authored for a dark
+    // bg and are too light on the 12%-tint admonition backgrounds over a light
+    // page bg. Each darkened (H fixed; C at gamut max, clipped where noted) to
+    // clear its admonition pair at threshold+0.1; carried from #2595.
+    success: "oklch(.470 .140 145)",
+    danger: "oklch(.505 .170 25)",
+    warning: "oklch(.490 .100 82)",
+    // C .135→.100 (gamut-clips at this L)
+    info: "oklch(.485 .122 245)",
+    mermaidNodeBg: { base: 1 },
+    mermaidText: { base: 4 },
+    mermaidLine: { base: 2 },
+    mermaidLabelBg: { base: 1 },
+    mermaidNoteBg: { base: 1 },
+    chatUserBg: { accent: 1 },
+    // Dark text on the amber user bubble (matches Default Dark).
+    chatUserText: { base: 4 },
+    // Merged onto bg (b0) — the chat assistant bubble reads as page-bg + border.
+    chatAssistantBg: { base: 0 },
+    chatAssistantText: { base: 4 },
+    imageOverlayBg: { base: 4 },
+    imageOverlayFg: { base: 0 },
+    // Search-result <mark>: amber highlighter fill with dark text — same look as
+    // Default Dark (an amber-on-white highlight reads identically in both modes).
+    matchedKeywordBg: "oklch(.700 .158 62)",
+    matchedKeywordFg: "oklch(.300 .003 65)"
+  }
+};
+const defaultColorSchemes = {
+  "Default Light": { ramps, map: lightMap },
+  "Default Dark": { ramps, map: darkMap }
+};
+export {
+  defaultColorSchemes
+};