@takazudo/zudo-doc 3.3.0 → 4.0.0

package/routes-src/_virtual.d.ts

@@ -29,6 +29,10 @@ declare module "virtual:zudo-doc-route-context" {
      *  `colorSchemes` to `zudoDocPreset` — `_chrome.tsx` falls back to
      *  `DEFAULT_SCHEME` in that case. */
     colorSchemes: Record<string, unknown> | null;
+    /** Resolved, enabled, ordered theme-pack registry (ADR
+     *  `docs/adr/theme-packs.md`, Decision 2). `null` when the routes plugin
+     *  did not thread one. */
+    themePackRegistry: Array<Record<string, unknown>> | null;
   };
 }
 

package/virtual-modules.d.ts

@@ -42,6 +42,10 @@ declare module "virtual:zudo-doc-route-context" {
      *  `colorSchemes` to `zudoDocPreset` — `_chrome.tsx` falls back to
      *  `DEFAULT_SCHEME` in that case. */
     colorSchemes: Record<string, unknown> | null;
+    /** Resolved, enabled, ordered theme-pack registry (ADR
+     *  `docs/adr/theme-packs.md`, Decision 2). `null` when the routes plugin
+     *  did not thread one. */
+    themePackRegistry: Array<Record<string, unknown>> | null;
   };
 }
 

package/zfb-config-shim.d.ts

@@ -52,6 +52,42 @@ declare module "zfb/config" {
     options?: Record<string, unknown>;
   }
 
+  /** Output mode for zfb fenced-code highlighting. */
+  export type CodeHighlightMode = "inline" | "class";
+
+  /** Fixed semantic taxonomy accepted by class-mode `roleClasses`. */
+  export type CodeHighlightRole =
+    | "escape"
+    | "operator"
+    | "comment"
+    | "string"
+    | "number"
+    | "constant"
+    | "keyword"
+    | "function"
+    | "type"
+    | "namespace"
+    | "property"
+    | "variable"
+    | "tag"
+    | "attribute"
+    | "punctuation"
+    | "inserted"
+    | "deleted"
+    | "heading";
+
+  /** zfb inline-theme or semantic class-mode configuration. */
+  export type CodeHighlightConfig = {
+    theme?: string;
+    themesDir?: string;
+    themeLight?: string;
+    themeDark?: string;
+    mode?: CodeHighlightMode;
+    classPrefix?: string;
+    roleClasses?: Partial<Record<CodeHighlightRole, string>>;
+    defaultStylesheet?: boolean;
+  };
+
   /**
    * Bundler options. Mirrors `BundleConfig` in crates/zfb/src/config.rs
    * and the published `@takazudo/zfb/config` (`dist/config.d.ts`). Added
@@ -113,25 +149,11 @@ declare module "zfb/config" {
      */
     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.
+     * Configures zfb's code highlighter. Class mode is mutually exclusive
+     * with every theme field and emits semantic role classes; inline mode
+     * retains the single/dual theme fields for general zfb consumers.
      */
-    codeHighlight?: {
-      theme?: string;
-      themesDir?: string;
-      themeLight?: string;
-      themeDark?: string;
-    };
+    codeHighlight?: CodeHighlightConfig;
     /**
      * Markdown link resolver (port of `remarkResolveMarkdownLinks`).
      * Mirrors `Config::resolve_markdown_links` in crates/zfb/src/config.rs

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

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

package/dist/theme/color-tweak-export-modal.d.ts

@@ -1,16 +0,0 @@
-import { type DesignTokenManifest } from "./design-token-serde.js";
-import { type ColorTweakState, type TweakState } from "./design-token-types.js";
-interface DesignTokenExportModalProps {
-    onClose: () => void;
-    /** Full unified tweak state — the modal serializes all four categories. */
-    state: TweakState;
-    /** Token manifest (spacing / font / size arrays) used by serialize() to
-     *  compute diff-only output. The caller is expected to forward the same
-     *  manifest the panel was configured with. */
-    manifest: DesignTokenManifest;
-    /** Color baseline used for diff-only output. Optional: callers without DOM
-     *  access (tests) can omit and we'll treat the entire color block as changed. */
-    colorDefaults?: ColorTweakState;
-}
-export default function ColorTweakExportModal({ onClose, state, manifest, colorDefaults, }: DesignTokenExportModalProps): import("preact").JSX.Element;
-export {};

package/dist/theme/color-tweak-export-modal.js

@@ -1,138 +0,0 @@
-import { jsx, jsxs } from "preact/jsx-runtime";
-import { useState, useEffect, useMemo, useRef } from "preact/hooks";
-import { serialize } from "./design-token-serde.js";
-import {
-} from "./design-token-types.js";
-const EXPORT_FILENAME_HINT = "zudo-doc-tokens.json";
-function resolveColorDefaults(fallback, explicit) {
-  return explicit ?? fallback;
-}
-function ColorTweakExportModal({
-  onClose,
-  state,
-  manifest,
-  colorDefaults
-}) {
-  const [copyLabel, setCopyLabel] = useState("Copy");
-  const [includeDefaults, setIncludeDefaults] = useState(false);
-  const dialogRef = useRef(null);
-  const copyTimerRef = useRef(null);
-  const code = useMemo(() => {
-    const baseline = resolveColorDefaults(state.color, colorDefaults);
-    const json = serialize(state, {
-      manifest,
-      includeDefaults,
-      colorDefaults: baseline
-    });
-    return JSON.stringify(json, null, 2);
-  }, [state, manifest, colorDefaults, includeDefaults]);
-  useEffect(() => {
-    const dialog = dialogRef.current;
-    if (!dialog) return;
-    dialog.showModal();
-    return () => {
-      if (dialog.open) dialog.close();
-    };
-  }, []);
-  useEffect(() => {
-    const dialog = dialogRef.current;
-    if (!dialog) return;
-    function handleClose() {
-      onClose();
-    }
-    dialog.addEventListener("close", handleClose);
-    return () => dialog.removeEventListener("close", handleClose);
-  }, [onClose]);
-  useEffect(() => {
-    return () => {
-      if (copyTimerRef.current) clearTimeout(copyTimerRef.current);
-    };
-  }, []);
-  function handleBackdropClick(e) {
-    const dialog = dialogRef.current;
-    if (!dialog) return;
-    const rect = dialog.getBoundingClientRect();
-    if (e.clientX < rect.left || e.clientX > rect.right || e.clientY < rect.top || e.clientY > rect.bottom) {
-      dialog.close();
-    }
-  }
-  async function handleCopy() {
-    let ok = false;
-    const dialog = dialogRef.current;
-    if (dialog) {
-      try {
-        const textarea = document.createElement("textarea");
-        textarea.value = code;
-        textarea.style.cssText = "position:fixed;opacity:0;left:-9999px";
-        dialog.appendChild(textarea);
-        textarea.focus();
-        textarea.select();
-        ok = document.execCommand("copy");
-        dialog.removeChild(textarea);
-      } catch {
-      }
-    }
-    if (!ok) {
-      try {
-        await navigator.clipboard.writeText(code);
-        ok = true;
-      } catch {
-      }
-    }
-    setCopyLabel(ok ? "Copied!" : "Failed");
-    if (copyTimerRef.current) clearTimeout(copyTimerRef.current);
-    copyTimerRef.current = setTimeout(() => setCopyLabel("Copy"), 2e3);
-  }
-  return /* @__PURE__ */ jsxs(
-    "dialog",
-    {
-      ref: dialogRef,
-      onClick: handleBackdropClick,
-      className: "mx-auto max-h-[80vh] w-full max-w-[46rem] overflow-y-auto border border-muted bg-surface p-hsp-xl backdrop:bg-bg/80",
-      style: { color: "var(--color-fg)", position: "fixed", top: "50%", left: "50%", transform: "translate(-50%, -50%)", userSelect: "text" },
-      children: [
-        /* @__PURE__ */ jsx("h2", { className: "mb-vsp-sm text-title font-bold text-fg", children: "Export Design Tokens" }),
-        /* @__PURE__ */ jsxs("p", { className: "mb-vsp-xs text-small text-muted", children: [
-          "Save as ",
-          /* @__PURE__ */ jsx("code", { className: "text-fg", children: EXPORT_FILENAME_HINT }),
-          " to feed this blob back into the panel (or hand to an AI assistant)."
-        ] }),
-        /* @__PURE__ */ jsxs("label", { className: "mb-vsp-xs flex items-center gap-x-hsp-sm text-small text-fg", children: [
-          /* @__PURE__ */ jsx(
-            "input",
-            {
-              type: "checkbox",
-              checked: includeDefaults,
-              onChange: (e) => setIncludeDefaults(e.currentTarget.checked)
-            }
-          ),
-          "Show defaults too"
-        ] }),
-        /* @__PURE__ */ jsx("pre", { className: "overflow-x-auto border border-muted bg-code-bg p-hsp-lg text-small text-code-fg", children: /* @__PURE__ */ jsx("code", { children: code }) }),
-        /* @__PURE__ */ jsxs("div", { className: "mt-vsp-sm flex items-center gap-x-hsp-md", children: [
-          /* @__PURE__ */ jsx(
-            "button",
-            {
-              type: "button",
-              onClick: handleCopy,
-              className: "border border-muted bg-surface px-hsp-lg py-vsp-2xs text-small text-fg transition-colors hover:border-accent hover:text-accent",
-              children: copyLabel
-            }
-          ),
-          /* @__PURE__ */ jsx(
-            "button",
-            {
-              type: "button",
-              onClick: () => dialogRef.current?.close(),
-              className: "border border-muted bg-surface px-hsp-lg py-vsp-2xs text-small text-muted transition-colors hover:border-fg hover:text-fg",
-              children: "Close"
-            }
-          )
-        ] })
-      ]
-    }
-  );
-}
-export {
-  ColorTweakExportModal as default
-};

package/dist/theme/design-token-serde.d.ts

@@ -1,183 +0,0 @@
-/**
- * Design-token SerDe — unified JSON export / import for the design-token panel.
- *
- * Supersedes the legacy TypeScript-object export in `export-code.ts`. The JSON
- * format is a single document covering all four token categories (color,
- * spacing, font, size) so an AI assistant can consume or emit a whole
- * design-token tweak in one round-trip.
- *
- * Format: `$schema = "zudo-doc-design-tokens/v3"`.
- *
- * v3 color slice — ramp-native, minimized (Color Ramp Restructure,
- * zudolab/zudo-doc#2584 / #2591; minimized to 5/3 in #2602)
- * -----------------------------------------------------------------------------------
- * The color block is the ramp-native `ColorScheme` from `color-scheme-utils.ts`:
- *   - `ramps` — the shared Tier-1 source of truth (`base[5]`, `accent[3]`,
- *     `state{danger,success,warning,info}`), emitted verbatim as OKLCH strings.
- *   - `map`   — the per-mode Tier-2 wiring (`bg`/`fg`/`selectionBg`/`selectionFg`
- *     + 23 `semantic` roles), each a `RampRef` (`{base:n}` / `{accent:n}` /
- *     `{state:role}` / a literal OKLCH string).
- *
- * The legacy v1 color slice (`palette: string[16]`, numeric `base`, `cursor`,
- * `semanticMappings`) is gone. Both `ramps` and `map` are plain JSON data, so
- * the color block is essentially a serialized `ColorScheme`.
- *
- * v1 → v3 migration (RESET, not remap)
- * ------------------------------------
- * A persisted v1 payload (detected by `$schema === "…/v1"`, a `palette` array,
- * or a numeric `base` block) has NO faithful mapping to the new model: the old
- * 16-slot ghostty palette + numeric semantic indices do not correspond to the
- * 5-base / 3-accent / 4-state ramps + `RampRef` wiring. Any remap would invent
- * colors and mislead the user, so `deserialize` RESETS the color slice to the
- * caller-supplied baseline (the current default scheme) and emits a
- * `console.warn` + a `warnings[]` entry — no throw, no blank screen. The
- * spacing/font/size slices are format-compatible across v1/v3 and are preserved.
- *
- * v2 → v3 migration (RESET, schema-label-only — zudolab/zudo-doc#2599)
- * ---------------------------------------------------------------------
- * `v2` was the ramp-native label BEFORE the base-12/accent-7 → base-5/accent-3
- * minimize (#2602); the shape (`ramps` + `map` of `RampRef`s) never changed, only
- * the ramp lengths did. That means a `v2`-labeled payload is ambiguous in a way
- * `v1` never was: `parseRamps` catches a wrong-length `ramps.base`/`ramps.accent`
- * array and falls back to baseline, but `parseMap`'s `RampRef` parser only
- * shape-checks a numeric index (`{base:11}`) — it does NOT range-check it against
- * the ramp length, because that tolerance is also relied on by legitimate
- * already-5/3 round-trip exports (see the `{accent:5}`-style fixtures in the test
- * file). So an out-of-range ref alone can't tell a genuinely-stale pre-5/3 export
- * apart from an intentionally-tolerated current-shape ref — both look identical
- * once parsed. Rather than guess from ref values, `v2` is retired as a whole:
- * ANY payload still carrying the `v2` label (regardless of whether its arrays
- * happen to already be 5/3-shaped) is treated as legacy and RESET to baseline,
- * exactly like v1. Only payloads relabeled `v3` are trusted to resolve cleanly
- * against the current ramp lengths.
- *
- * Diff-only by default
- * --------------------
- * `serialize()` only emits tokens the user has actually changed relative to
- * the provided `colorDefaults` (for the color block) and the manifest defaults
- * (for spacing / font / size). Pass `includeDefaults: true` to dump the full
- * state instead. The whole-category keys (`color`, `spacing`, `font`, `size`)
- * are omitted entirely when nothing in them differs. For the color block the
- * `ramps` and `map` sub-blocks are each emitted whole (not per-stop / per-role
- * diffed) when they differ from the baseline — the ramp-native shape has no
- * stable per-slot index to diff against, and a whole-block emit round-trips
- * cleanly against the same baseline.
- *
- * Spacing / font / size keys use CSS variable names (`"--spacing-hsp-md"`) —
- * the external schema — rather than the internal token id (`"hsp-md"`). This
- * keeps the file human-readable and agnostic of our internal manifest.
- * `deserialize()` maps them back; unknown CSS vars are reported via
- * `unknownTokens` so the UI can surface them.
- *
- * Read-only manifest tokens (e.g. `--spacing-0`, `--zd-sidebar-w` with
- * `clamp()`) are skipped in both directions.
- *
- * W3B (#1730 — Generator Pages Migration): moved from
- * `src/utils/design-token-serde.ts` into v2. The manifest tokens
- * (`SPACING_TOKENS` / `FONT_TOKENS` / `SIZE_TOKENS`) are no longer
- * imported from the host's `@/config/design-tokens-manifest` — the
- * caller now passes them through `SerializeOptions.manifest` /
- * `DeserializeOptions.manifest`, preserving consumer override hooks.
- */
-interface TokenDef {
-    /** Stable id used as the Record key in persisted state (e.g. `hsp-2xs`). */
-    id: string;
-    /** CSS custom property name written to `:root` (e.g. `--zd-spacing-hgap-2xs`). */
-    cssVar: string;
-    /** Default value as a CSS length string (e.g. `0.125rem`). */
-    default: string;
-    /** Read-only tokens are displayed but not editable. */
-    readonly?: true;
-}
-import { type TweakState } from "./design-token-types.js";
-import { type ColorScheme, type ModeMap, type Ramps } from "../color-scheme-utils.js";
-export declare const DESIGN_TOKEN_SCHEMA: "zudo-doc-design-tokens/v3";
-/** External JSON color block — a (possibly diff-only) serialized `ColorScheme`.
- *  Both sub-blocks are optional: in diff-only output an unchanged `ramps` or
- *  `map` is omitted and filled from the baseline on deserialize. */
-export interface DesignTokenJsonColor {
-    ramps?: Ramps;
-    map?: ModeMap;
-}
-/** External token map keyed by CSS var name. */
-export type DesignTokenJsonOverrides = Record<string, string>;
-export interface DesignTokenJson {
-    $schema: typeof DESIGN_TOKEN_SCHEMA;
-    exportedAt: string;
-    color?: DesignTokenJsonColor;
-    spacing?: DesignTokenJsonOverrides;
-    font?: DesignTokenJsonOverrides;
-    size?: DesignTokenJsonOverrides;
-}
-/**
- * Token manifest the caller hands in — the consumer's
- * `src/config/design-tokens-manifest.ts` (or generator override). v2
- * doesn't ship its own manifest; this is intentionally a caller concern
- * so each consumer keeps full control over the editable token set.
- */
-export interface DesignTokenManifest {
-    spacing: readonly TokenDef[];
-    font: readonly TokenDef[];
-    size: readonly TokenDef[];
-}
-export interface SerializeOptions {
-    /** Token manifest (spacing / font / size arrays) used to compute
-     *  diff-only output and resolve CSS-var names. Required. */
-    manifest: DesignTokenManifest;
-    /** When true, dump full state (whole `ramps` + `map`, all token manifest
-     *  defaults merged in). Default: diff-only. */
-    includeDefaults?: boolean;
-    /** Color baseline to diff against — typically the active scheme's initial
-     *  `ColorScheme`. Required for meaningful color-diff output; callers that
-     *  don't have it available (e.g. tests without DOM) can omit it and we'll
-     *  treat the whole color block as changed. */
-    colorDefaults?: ColorScheme;
-    /** Override the `exportedAt` stamp (test-only). */
-    now?: () => Date;
-}
-export interface DeserializeResult {
-    /** The reconstructed tweak state, with unknown-token values dropped. */
-    state: TweakState;
-    /** CSS var names present in the payload that don't match any known token. */
-    unknownTokens: string[];
-    /** Human-readable errors that did not prevent a state from being produced
-     *  (e.g. "v1 payload detected; color reset to default"). */
-    warnings: string[];
-}
-export interface DeserializeOptions {
-    /** Token manifest (spacing / font / size arrays) used to resolve CSS-var
-     *  names back to internal token ids. Required. */
-    manifest: DesignTokenManifest;
-    /** Color baseline used to fill in fields absent from the payload (diff-only
-     *  exports are missing most fields by design) and as the reset target for a
-     *  v1 migration. Typically the active scheme's initial `ColorScheme`. */
-    colorDefaults?: ColorScheme;
-}
-/** Thrown when the payload is not a recognized schema object. The error
- *  `.reason` helps the UI render a precise inline message. A v1 payload is NOT
- *  thrown for — it is migrated (see `deserialize`). */
-export declare class DesignTokenSchemaError extends Error {
-    readonly reason: "not-object" | "schema-missing" | "schema-mismatch";
-    readonly actualSchema?: unknown;
-    constructor(reason: "not-object" | "schema-missing" | "schema-mismatch", message: string, actualSchema?: unknown);
-}
-/**
- * Produce the external JSON document for a given tweak state.
- *
- * By default this is diff-only against `opts.colorDefaults` + manifest
- * defaults; set `opts.includeDefaults = true` to dump everything.
- */
-export declare function serialize(state: TweakState, opts: SerializeOptions): DesignTokenJson;
-/**
- * Parse a design-token JSON document and lift it back into a tweak state.
- *
- * Throws `DesignTokenSchemaError` on schema mismatch / non-object input. A v1
- * (palette-based) payload is NOT thrown for — its color slice is reset to the
- * baseline default (see the v1→v2 migration note at the top). Any CSS var name
- * that doesn't match a known manifest entry is collected into `unknownTokens`.
- *
- * Missing fields fall back to `opts.colorDefaults` (or, absent that, a
- * minimal neutral default) so the result is always a valid `TweakState`.
- */
-export declare function deserialize(input: unknown, opts: DeserializeOptions): DeserializeResult;
-export {};