create-zudo-doc 3.2.0 → 3.3.0

package/templates/base/src/styles/global.css

@@ -1,353 +1,28 @@
-/* Cascade-layer order for the flow-space fix (zudolab/zudo-doc#2082 / #2109):
- *   zd-preflight  — Tailwind's preflight reset (incl. `* { margin: 0 }`)
- *   zd-flow       — the .zd-content flow-space margin-top rule (below)
- *   (unlayered)   — `tailwindcss/utilities` (mt-* etc.) — highest priority
- * Unlayered always beats any layer, so `mt-*` utilities win over the flow
- * rule; the flow rule (zd-flow) sits above zd-preflight so it still beats the
- * preflight `margin: 0` reset and the .zd-content vertical rhythm is preserved.
- * Preflight is the de-facto lowest-priority origin already, so moving it into
- * the lowest layer is observably inert for every other author rule (which stay
- * unlayered and continue to outrank it). */
+/* Cascade layers: preflight → flow → (unlayered utilities). Tokens/base rules
+   ship from @takazudo/zudo-doc/theme.css.
+   NOTE: the `@takazudo/zdtp/styles.css` import is intentionally NOT here —
+   it is inserted right after the @layer line above, ONLY when
+   designTokenPanel is selected (see features/design-token-panel.ts). It
+   can't ship unconditionally because it pulls in zdtp's own bytes. */
 @layer zd-preflight, zd-flow;
 @import "tailwindcss/preflight" layer(zd-preflight);
 @import "tailwindcss/utilities";
 
-/* ========================================
- * @takazudo/zudo-doc package safelist
- *
- * The package ships a build-generated safelist at `dist/safelist.css`
- * (zudolab/zudo-doc#1993). Importing it via the module resolver is
- * reliable across all consumer environments — the same module-resolver
- * code path used for any feature stylesheet injected at the
- * `@slot:global-css:feature-styles` anchor below.
- *
- * Why not @source the package dist/ glob? The old approach
- * (`@source "../../node_modules/@takazudo/zudo-doc/dist/**"`) was
- * unreliable: pnpm stores packages in a content-addressable store and
- * surfaces them to node_modules via symlinks. Tailwind v4's file
- * scanner does not reliably traverse those symlinks, so arbitrary-value
- * candidates (e.g. `w-[var(--zd-sidebar-w)]`, `h-[calc(100vh-3.5rem)]`)
- * were intermittently dropped across rebuilds (zudolab/zudo-doc#1971,
- * #1989). The package-generated `@source inline()` in dist/safelist.css
- * contains the full set, extracted at package build time — no drift, no
- * symlink traversal, auto-syncs on package upgrade (zudolab/zudo-doc#1994).
- * ======================================== */
-
+/* Package-shipped tokens, safelist, content typography, and feature CSS.
+   Order is load-bearing — theme.css MUST precede features.css. Do not reorder. */
+@import "@takazudo/zudo-doc/theme.css";
 @import "@takazudo/zudo-doc/safelist.css";
-
-/* Content typography (`.zd-content` rules + admonitions + mermaid layout).
-   Shipped by @takazudo/zudo-doc as the single source of truth — do not inline
-   these rules here (they used to live here and drifted; see
-   zudolab/zudo-doc#2188). The @layer zd-flow order it relies on is declared
-   above (line 11); the safelist import above generates the component utilities
-   its headings/links/etc. depend on. */
 @import "@takazudo/zudo-doc/content.css";
-/* Non-island feature CSS (code block buttons, syntect light-dark token rule,
-   .zd-html-preview-code, KaTeX, sidebar toggle geometry, view-transition chrome,
-   .ai-chat-md, .zd-enlarge*, .zd-mermaid*).
-   Shipped by @takazudo/zudo-doc as single source of truth. See zudolab/zudo-doc#2331. */
+@import "@takazudo/zudo-doc/page-loading.css";
 @import "@takazudo/zudo-doc/features.css";
-/* @slot:global-css:imports */
-
-/* ========================================
- * Tailwind v4 content sources
- *
- * Without a `.git` directory in the project root Tailwind v4's content
- * scanner falls back to explicit @source directives for class detection.
- * Builds that run outside a git checkout (E2E fixtures, CI containers
- * that copy the source tree without history, etc.) hit this fallback,
- * and zfb's default content roots only cover `pages/`. Components live
- * outside pages/, so these directives ensure the consumer's own code is
- * always scanned for utility classes. The package's utilities are now
- * covered by the @import above — these directives cover consumer code only.
- * ======================================== */
 
-@source "src/components/**/*.{tsx,ts,jsx,js,mdx,md}";
+/* Scan this project's own source for Tailwind utility classes. */
 @source "src/content/**/*.{mdx,md}";
-@source "src/hooks/**/*.{tsx,ts,jsx,js}";
-@source "src/utils/**/*.{tsx,ts,jsx,js}";
+@source "src/components/**/*.{tsx,ts,jsx,js}";
 @source "pages/**/*.{tsx,ts,jsx,js}";
 
-/* ========================================
- * Design Token System
- *
- * Tight token strategy: import preflight + utilities only (no default theme).
- * Only project-specific tokens are available.
- *
- * Base roles: --zd-bg/--zd-fg/--zd-selection-bg/--zd-selection-fg + ramps
- * (--palette-base-0..4 / --palette-accent-0..2 / --palette-state-*) +
- * 23 --zd-{role} semantic tokens, all injected by ColorSchemeProvider.
- * Tailwind tokens: registered below via @theme
- * ======================================== */
-
+/* ── Your token overrides ──────────────────────────────────────────────
+   Override any default @theme token from @takazudo/zudo-doc/theme.css here. */
 @theme {
-  /* ========================================
-   * Project tight-token color reset
-   *
-   * Wipes all Tailwind default color tokens (`--color-*`) so only
-   * project-defined palette and semantic tokens remain. This enforces the
-   * tight-token policy: "NEVER use Tailwind default colors" (per Color Rules
-   * in src/CLAUDE.md). Project color tokens (defined below) are added back
-   * after this reset.
-   *
-   * The upstream split-import fix (zfb#159 / 9e37551, shipped in f68a9ba)
-   * eliminated the original leak cause (zfb no longer prepends the full
-   * @import "tailwindcss" bundle). The reset is retained as an explicit
-   * design guardrail — it prevents accidental default palette bleed from any
-   * future upstream change and keeps the project's color surface intentional.
-   *
-   * NOT reset: `--spacing` (the base spacing scale, default 0.25rem).
-   * Tailwind spacing utilities compute as calc(var(--spacing) * N); wiping
-   * `--spacing` collapses them to zero (observed in Wave 4 Sub-7 #1403).
-   * ======================================== */
-  --color-*: initial;
-
-  /* ========================================
-   * Colors — Three-tier token system
-   * ======================================== */
-
-  /* ── Base ── */
-  --color-bg: var(--zd-bg);
-  --color-fg: var(--zd-fg);
-  --color-sel-bg: var(--zd-selection-bg);
-  --color-sel-fg: var(--zd-selection-fg);
-
-  /* ── Semantic aliases ── */
-  --color-surface: var(--zd-surface);
-  --color-muted: var(--zd-muted);
-  --color-accent: var(--zd-accent);
-  --color-accent-hover: var(--zd-accent-hover);
-  --color-code-bg: var(--zd-code-bg);
-  --color-code-fg: var(--zd-code-fg);
-  --color-success: var(--zd-success);
-  --color-danger: var(--zd-danger);
-  --color-warning: var(--zd-warning);
-  --color-info: var(--zd-info);
-  /* Overlay is intentionally theme-independent (always dark, not scheme-driven) */
-  --color-overlay: #000;
-  /* The page-loading overlay scrim token is feature-gated: the dynamicPageTransition
-     feature injects it into @slot:global-css:theme-tokens when enabled, so it is
-     intentionally absent from this base @theme block (the host showcase global.css
-     carries it inline only because the host is fully featured). Do not re-add it here. */
-  --color-image-overlay-bg: var(--zd-image-overlay-bg);
-  --color-image-overlay-fg: var(--zd-image-overlay-fg);
-  /* --color-mermaid-* aliases removed: mermaid-init-script.ts reads --zd-mermaid-* directly;
-     these @theme registrations were unused (no Tailwind utility references). --zd-mermaid-*
-     injection in color-scheme-utils.ts is preserved and remains the live source. */
-  --color-chat-user-bg: var(--zd-chat-user-bg);
-  --color-chat-user-text: var(--zd-chat-user-text);
-  --color-chat-assistant-bg: var(--zd-chat-assistant-bg);
-  --color-chat-assistant-text: var(--zd-chat-assistant-text);
-  --color-matched-keyword-bg: var(--zd-matched-keyword-bg);
-  --color-matched-keyword-fg: var(--zd-matched-keyword-fg);
-  /* @slot:global-css:theme-tokens */
-
-  /* ========================================
-   * Spacing — hsp (horizontal) + vsp (vertical)
-   * ======================================== */
-  --spacing-0: 0;
-  --spacing-px: 1px;
-
-  /* Horizontal spacing (7 steps) */
-  --spacing-hsp-2xs: 0.125rem;   /* 2px  — tight inline */
-  --spacing-hsp-xs: 0.375rem;   /* 6px  — compact inline */
-  --spacing-hsp-sm: 0.5rem;     /* 8px  — small padding */
-  --spacing-hsp-md: 0.75rem;    /* 12px — default gaps */
-  --spacing-hsp-lg: 1rem;       /* 16px — standard padding */
-  --spacing-hsp-xl: 1.5rem;     /* 24px — generous padding */
-  --spacing-hsp-2xl: 2rem;      /* 32px — large padding */
-
-  /* Vertical spacing (8 steps) */
-  --spacing-vsp-3xs: 0.25rem;     /* 4px — hairline gap */
-  --spacing-vsp-2xs: 0.4375rem;   /* 7px — tight gap */
-  --spacing-vsp-xs: 0.875rem;    /* 14px — small gap */
-  --spacing-vsp-sm: 1.25rem;     /* 20px — compact gap */
-  --spacing-vsp-md: 1.5rem;      /* 24px — standard gap */
-  --spacing-vsp-lg: 1.75rem;     /* 28px — section gap */
-  --spacing-vsp-xl: 2.5rem;      /* 40px — large section gap */
-  --spacing-vsp-2xl: 3.5rem;     /* 56px — page-level gap */
-
-  /* ========================================
-   * Element sizes — semantic icon dimensions
-   * ======================================== */
-  --spacing-icon-xs: 0.75rem;    /* 12px — inline meta icons, chevrons */
-  --spacing-icon-sm: 1rem;       /* 16px — standard UI icons */
-  --spacing-icon-md: 1.25rem;    /* 20px — medium emphasis icons */
-  --spacing-icon-lg: 1.5rem;     /* 24px — large / mobile icons */
-
-  /* Image overlay button chrome */
-  --spacing-image-overlay-inset: 0.5rem;  /* 8px — overlay button corner inset + internal padding */
-
-  /* ========================================
-   * Elevation — the tight `@import "tailwindcss/utilities"` (no default
-   * @theme) drops Tailwind's default shadow scale, so `shadow-*` utilities
-   * generate nothing. Re-add the one elevation the components use: header
-   * and version-switcher dropdown panels apply `shadow-lg`. Value is
-   * Tailwind v4's default shadow-lg; the black is intentionally
-   * theme-independent (a drop shadow is absence of light, not a themed color).
-   * ======================================== */
-  --shadow-lg: 0 10px 15px -3px rgb(0 0 0 / 0.1), 0 4px 6px -4px rgb(0 0 0 / 0.1);
-
-  /* ========================================
-   * Typography
-   * ======================================== */
-
-  /* ── Tier 2: Semantic font-size tokens (reference Tier 1 scale only) ── */
-  --text-micro:      var(--text-scale-2xs);  /* 12px — compact panel labels, color swatch annotations */
-  --text-caption:    var(--text-scale-xs);   /* labels, timestamps */
-  --text-small:      var(--text-scale-sm);   /* secondary text, nav items */
-  --text-body:       var(--text-scale-md);   /* paragraphs, default */
-  --text-title:      var(--text-scale-lg);   /* card titles, section labels */
-  --text-heading:    var(--text-scale-xl);   /* page headings */
-  --text-display:    var(--text-scale-2xl);  /* hero text */
-
-  /* Font families */
-  --font-sans: system-ui, sans-serif;
-  --font-mono: ui-monospace, monospace;
-
-  /* Font weights (4 steps) */
-  --font-weight-normal: 400;
-  --font-weight-medium: 500;
-  --font-weight-semibold: 600;
-  --font-weight-bold: 700;
-
-  /* Line heights (4 steps) */
-  --leading-tight: 1.25;
-  --leading-snug: 1.375;
-  --leading-normal: 1.5;
-  --leading-relaxed: 1.625;
-
-  /* Letter spacing / tracking (4 steps) */
-  --tracking-tight: -0.025em;   /* headings, display text */
-  --tracking-normal: normal;    /* browser default — resets any inherited tracking */
-  --tracking-wide: 0.05em;      /* labels, UI text */
-  --tracking-wider: 0.1em;      /* small caps, decorative */
-
-  /* ========================================
-   * Border radius (3 steps)
-   * ======================================== */
-  --radius-DEFAULT: 0.25rem;    /* 4px — rounded */
-  --radius-lg: 0.5rem;          /* 8px — rounded-lg */
-  --radius-full: 9999px;        /* rounded-full */
-
-  /* ========================================
-   * Breakpoints (3 steps)
-   * ======================================== */
-  --breakpoint-sm: 640px;
-  --breakpoint-lg: 1024px;
-  --breakpoint-xl: 1280px;
+  /* e.g. --color-accent: oklch(0.6 0.2 250); */
 }
-
-/* ========================================
- * Z-index tiers — semantic, single-namespace scale.
- *
- * The @theme block below is GENERATED from src/config/z-index-tokens.ts
- * (the single source of truth) by `pnpm gen:z-index`. Tailwind v4 reads the
- * --z-index-<name> theme key and generates a `z-<name>` utility, so e.g.
- * --z-index-toolbar: 20 produces `.z-toolbar { z-index: 20 }`; raw CSS can
- * also reference `z-index: var(--z-index-<name>)`. `pnpm check:z-index` fails
- * on drift. Do NOT hand-edit between the BEGIN/END markers.
- * ======================================== */
-  /* GENERATED:Z_INDEX_BEGIN
-   * GENERATED:Z_INDEX — do not hand-edit; run pnpm gen:z-index.
-   * Source of truth: src/config/z-index-tokens.ts. Tailwind v4 reads the
-   * --z-index-<name> theme key and generates a z-<name> utility. */
-  @theme {
-    --z-index-content: 0;
-    --z-index-local-1: 1;
-    --z-index-local-2: 2;
-    --z-index-local-3: 3;
-    --z-index-sidebar: 10;
-    --z-index-toolbar: 20;
-    --z-index-dropdown: 30;
-    --z-index-popover: 40;
-    --z-index-modal-backdrop: 50;
-    --z-index-modal: 60;
-    --z-index-toast: 70;
-    --z-index-tooltip: 80;
-    --z-index-drag: 90;
-  }
-  /* GENERATED:Z_INDEX_END */
-
-:root {
-  /* Default responsive range; sidebar-resizer.ts allows 192–448px for explicit resizing. */
-  --zd-sidebar-w: clamp(14rem, 20vw, 22rem);
-
-  /* ── Tier 1: Abstract font-size scale (raw values — NOT for direct component use) ── */
-  /* Used only as a source of truth for Tier 2 semantic tokens above. */
-  --text-scale-2xs: 0.75rem;    /* 12px */
-  --text-scale-xs:  0.875rem;   /* 14px */
-  --text-scale-sm:  1rem;       /* 16px */
-  --text-scale-md:  1.2rem;     /* 19.2px */
-  --text-scale-lg:  1.4rem;     /* 22.4px */
-  --text-scale-xl:  3rem;       /* 48px */
-  --text-scale-2xl: 3.75rem;    /* 60px */
-
-  --default-transition-duration: 150ms; /* consumed by image-enlarge and hash-link opacity fade */
-  --zd-transition-slow: 200ms;          /* sidebar transform/visibility and content-band max-width */
-  --zd-transition-slower: 300ms;        /* view-transition fade-in (contentFadeIn animation) */
-  --zd-header-h: 80px;                  /* sticky header height; consumed by scroll-margin-top on [id] anchors */
-}
-
-/* ========================================
- * Base styles
- * ======================================== */
-
-[id] {
-  scroll-margin-top: var(--zd-header-h);
-}
-
-body {
-  background-color: var(--color-bg);
-  color: var(--color-fg);
-}
-
-::selection {
-  background-color: var(--color-sel-bg);
-  color: var(--color-sel-fg);
-}
-
-@layer base {
-  a {
-    text-underline-offset: 4px;
-  }
-  button {
-    cursor: pointer;
-  }
-  :focus-visible {
-    outline: 2px solid var(--color-accent);
-    outline-offset: 2px;
-  }
-}
-
-/* ── Search highlight ── */
-[data-search-results] mark {
-  background-color: var(--color-matched-keyword-bg);
-  color: var(--color-matched-keyword-fg);
-  padding: 0;
-  border-radius: 2px;
-}
-
-/* Version-switcher responsive visibility (moved out of the component to
- * avoid <style>-inside-<div> HTML5 content-model violation; required when
- * the i18nVersion feature ships a <VersionSwitcher> wrapped in
- * `<div class="hidden lg:block">`. Inert when no version-switcher is on
- * the page. */
-@media (min-width: 64rem) {
-  .hidden:has(> [data-version-switcher]) {
-    display: block;
-  }
-}
-
-/* ── Find-in-page highlight (W7A: unconditional — Tauri feature gates at runtime) ── */
-.find-match {
-  background-color: color-mix(in oklch, var(--color-warning) 40%, transparent);
-  border-radius: 2px;
-}
-.find-match-active {
-  background-color: color-mix(in oklch, var(--color-warning) 70%, transparent);
-  border-radius: 2px;
-  outline: 2px solid color-mix(in oklch, var(--color-warning) 90%, transparent);
-}
-
-/* @slot:global-css:feature-styles */

package/templates/base/tsconfig.json

@@ -1,36 +1,13 @@
 {
-  "$schema": "https://json.schemastore.org/tsconfig",
+  "extends": "@takazudo/zudo-doc/tsconfig.base.json",
+  "include": ["src", "pages", "zfb.config.ts"],
   "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": ".",
     "paths": {
       "@/*": ["src/*"],
-      "#doc-history-meta": [".zfb/doc-history-meta.json"],
       "react": ["./node_modules/preact/compat/"],
       "react/jsx-runtime": ["./node_modules/preact/jsx-runtime"],
       "react-dom": ["./node_modules/preact/compat/"]
     }
-  },
-  "exclude": ["dist", "e2e/fixtures", "packages", "pages", "worktrees", "vendor", "src/**/__tests__", "vitest.config.ts"]
+  }
 }

package/templates/features/i18n/files/pages/[locale]/docs/[[...slug]].tsx

@@ -0,0 +1,88 @@
+/** @jsxRuntime automatic */
+/** @jsxImportSource preact */
+// Locked manifest (#2653 Decision 4, i18n addendum): the locale-prefixed
+// counterpart of pages/docs/[[...slug]].tsx — required for the same reason
+// (injected DYNAMIC routes 404 in `zfb dev`). Self-contained: only the three
+// sanctioned package entrypoints — no `pages/lib`, no `@/config`. Mirrors
+// the package's own `routes/locale-docs-slug.tsx` shape, rebuilt from the
+// route-context payload instead of the package-internal `_context.js`.
+//
+// Per-locale content dir + fallback notice (ported from
+// packages/zudo-doc/src/routes/locale-docs-slug.tsx and the showcase's
+// pages/[locale]/docs/[[...slug]].tsx): each route carries the locale's own
+// content directory (`getLocaleConfig(locale).dir`) and an `isFallback` flag.
+// A page that only exists in the default locale is served as an untranslated
+// FALLBACK — it must (a) read doc-history from the DEFAULT-locale content dir
+// (not the translated one, which has no such file), and (b) thread
+// `isFallback` so the chrome renders the "not translated yet" notice. Dropping
+// either — as this stub previously did by hardcoding `docsDir` for every
+// locale and never passing `isFallback` — silently breaks translated pages.
+//
+// docHistory note: same as the default-locale stub — when docHistory is
+// selected, the generator patches this file too.
+
+import type { JSX } from "preact";
+import { routeContext } from "virtual:zudo-doc-route-context";
+import {
+  createRouteContext,
+  type RouteContextPayload,
+} from "@takazudo/zudo-doc/route-context";
+import { createChrome } from "@takazudo/zudo-doc/chrome";
+
+const ctx = routeContext as unknown as RouteContextPayload;
+const routeCtx = createRouteContext(ctx);
+const { renderDocPage } = createChrome(routeCtx);
+
+export const frontmatter = { title: "Docs" };
+
+export function paths(): Array<{
+  params: { locale: string; slug: string[] };
+  props: unknown;
+}> {
+  const result: Array<{
+    params: { locale: string; slug: string[] };
+    props: unknown;
+  }> = [];
+
+  for (const locale of Object.keys(routeCtx.settings.locales)) {
+    const contentDir =
+      routeCtx.getLocaleConfig(locale)?.dir ?? routeCtx.settings.docsDir;
+    const source = routeCtx.resolveNavSource(locale, undefined, {
+      applyDefaultLocaleOnlyFilter: true,
+      keepUnlisted: true,
+    });
+    for (const item of routeCtx.buildDocRouteEntries({
+      source,
+      locale,
+      routeSig: `locale-docs;${locale}`,
+    })) {
+      result.push({
+        params: { locale, slug: item.slugParams },
+        props: {
+          ...(item.props as Record<string, unknown>),
+          // Fallback pages exist only in the default locale, so their
+          // doc-history lives under the EN docsDir; translated pages read
+          // their own locale dir.
+          contentDir: item.isFallback ? routeCtx.settings.docsDir : contentDir,
+          isFallback: item.isFallback,
+        },
+      });
+    }
+  }
+
+  return result;
+}
+
+type PageArgs = {
+  params: { locale: string; slug: string[] };
+  contentDir: string;
+  isFallback: boolean;
+} & Record<string, unknown>;
+
+export default function LocaleDocsPage(props: PageArgs): JSX.Element {
+  return renderDocPage(props as never, {
+    locale: props.params.locale,
+    isFallback: props.isFallback,
+    docHistoryContentDir: props.contentDir,
+  });
+}

package/templates/features/tagGovernance/files/scripts/tags-suggest.ts

@@ -16,7 +16,9 @@ import { parseArgs } from "node:util";
 import matter from "gray-matter";
 
 import { tagVocabulary } from "../src/config/tag-vocabulary";
-import type { TagVocabularyEntry } from "../src/config/tag-vocabulary-types";
+// Minimal-scaffold cutover (epic zudolab/zudo-doc#2651): the standalone
+// `tag-vocabulary-types.ts` shim is gone — the type ships from the package.
+import type { TagVocabularyEntry } from "@takazudo/zudo-doc/settings";
 
 const DEFAULT_HOST = "http://localhost:11434";
 const DEFAULT_MODEL = "qwen2.5:7b";

package/dist/settings-gen.d.ts

@@ -1,2 +0,0 @@
-import type { UserChoices } from "./prompts.js";
-export declare function generateSettingsFile(choices: UserChoices): string;