@zenginui/registry 0.1.0

package/dist/create.js

@@ -0,0 +1,437 @@
+import { existsSync, mkdirSync, readdirSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { createEngine, loadConfigFile, readProjectFiles, resolveConfig } from "@zenginui/engine";
+import { installItems, STYLES_INDEX_HEAD } from "./install.js";
+import { resolveItems } from "./resolve.js";
+import { LAYOUT } from "./schema.js";
+import { applyTheme } from "./theme.js";
+import { writeTokensCss } from "./tokens.js";
+/** Versions pinned into a generated package.json. One place to bump. */
+export const VERSIONS = {
+    react: "^19.3.0",
+    "react-dom": "^19.3.0",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "@vitejs/plugin-react": "^6.1.1",
+    typescript: "^5.9.2",
+    vite: "^8.3.0",
+    next: "^16.1.0",
+    storybook: "^10.6.0",
+    "@storybook/react-vite": "^10.6.0",
+    "@storybook/addon-docs": "^10.6.0",
+    "@storybook/addon-a11y": "^10.6.0",
+    zengin: "^0.1.0",
+};
+export async function createProject(opts) {
+    const dir = resolve(opts.dir);
+    const name = opts.name ?? basename(dir);
+    const template = opts.template ?? "blank";
+    const storybook = opts.storybook ?? true;
+    const framework = opts.framework ?? "vite";
+    if (existsSync(dir) && readdirSync(dir).length > 0)
+        throw new Error(`${dir} exists and is not empty.`);
+    if (!/^[a-z0-9][a-z0-9._-]*$/.test(name))
+        throw new Error(`"${name}" is not a valid package name. Use lowercase letters, digits, dots, dashes.`);
+    const index = await opts.source.index();
+    const version = index.version;
+    const templateItem = index.items.find((i) => i.name === template && i.type === "template");
+    if (!templateItem) {
+        const templates = index.items.filter((i) => i.type === "template").map((i) => i.name);
+        throw new Error(`No template "${template}". Templates: ${templates.join(", ")}.`);
+    }
+    mkdirSync(dir, { recursive: true });
+    const write = (rel, content) => {
+        mkdirSync(dirname(join(dir, rel)), { recursive: true });
+        writeFileSync(join(dir, rel), content);
+    };
+    // Base files first; the template may overwrite any of them (its own main.tsx, brand.css, index.html).
+    if (framework === "vite") {
+        write("index.html", INDEX_HTML(name));
+        write("src/main.tsx", MAIN_TSX);
+        write("vite.config.ts", VITE_CONFIG);
+    }
+    else {
+        write("next.config.ts", NEXT_CONFIG);
+        write("src/app/page.tsx", NEXT_PAGE);
+    }
+    write("src/theme/brand.css", BRAND_CSS);
+    write(LAYOUT.stylesIndex, STYLES_INDEX_HEAD);
+    write("tsconfig.json", framework === "vite" ? TSCONFIG(storybook) : TSCONFIG_NEXT(storybook));
+    write(".gitignore", framework === "vite" ? GITIGNORE : GITIGNORE + ".next/\nnext-env.d.ts\n");
+    write("zengin.config.yaml", ZENGIN_CONFIG(version));
+    write(".mcp.json", MCP_JSON);
+    write(".claude/settings.json", CLAUDE_SETTINGS);
+    if (storybook) {
+        write(".storybook/main.ts", STORYBOOK_MAIN);
+        write(".storybook/preview.tsx", STORYBOOK_PREVIEW);
+        write(`${LAYOUT.storiesDir}/manifest.ts`, STORIES_MANIFEST);
+    }
+    const resolved0 = await resolveItems(opts.source, [template]);
+    // On Next the template's entry point and page become the root layout and the page: the same imports,
+    // the same title and fonts link, the App mounted client-side so the SPA-style templates run unchanged.
+    const items = framework === "next" ? resolved0.map((i) => (i.type === "template" ? { ...i, files: i.files.filter((f) => f.path !== "index.html" && f.path !== "src/main.tsx") } : i)) : resolved0;
+    const install = installItems({ projectDir: dir, items: storybook ? items : items.map((i) => ({ ...i, files: i.files.filter((f) => f.kind !== "story") })), version, force: true });
+    if (framework === "next") {
+        const tpl = resolved0.find((i) => i.type === "template");
+        const html = tpl?.files.find((f) => f.path === "index.html")?.content ?? INDEX_HTML(name);
+        const main = tpl?.files.find((f) => f.path === "src/main.tsx")?.content ?? MAIN_TSX;
+        write("src/app/layout.tsx", NEXT_LAYOUT({ name, html, main }));
+    }
+    write("package.json", packageJson({ name, install, storybook, local: opts.local, framework, mock: items.some((i) => i.type === "template" && i.files.some((f) => f.path === "mock.json")) }));
+    write("README.md", README(name, template, install.components, framework));
+    if (opts.theme)
+        await applyTheme({ projectDir: dir, name: opts.theme, source: opts.source });
+    const tokens = writeTokensCss(join(dir, LAYOUT.definitionsDir), join(dir, "src/styles/generated/tokens.css"));
+    // The engine on the result. A fresh project must be clean; anything else is a registry defect.
+    const { config, dir: projectDir } = loadConfigFile(join(dir, "zengin.config.yaml"));
+    const resolved = resolveConfig(config, projectDir);
+    const engine = await createEngine(resolved);
+    const files = readProjectFiles(projectDir, resolved.scope.include, resolved.scope.exclude);
+    const violations = engine.check(files).length;
+    return { dir, name, template, framework, version, install, tokens, violations };
+}
+function packageJson(opts) {
+    const next = opts.framework === "next";
+    // `link:` symlinks the checkout's package and uses its own node_modules, so workspace deps resolve. pnpm honors it; npm needs the release.
+    const z = (pkg) => (opts.local ? `link:${resolve(opts.local, "packages", pkg).replace(/\\/g, "/")}` : VERSIONS.zengin);
+    const dependencies = sortKeys({ react: VERSIONS.react, "react-dom": VERSIONS["react-dom"], ...(next ? { next: VERSIONS.next } : {}), ...opts.install.dependencies });
+    const devDependencies = sortKeys({
+        "@types/react": VERSIONS["@types/react"],
+        "@types/react-dom": VERSIONS["@types/react-dom"],
+        ...(!next || opts.storybook ? { "@vitejs/plugin-react": VERSIONS["@vitejs/plugin-react"] } : {}),
+        "@zenginui/cli": z("cli"),
+        "@zenginui/hook": z("hook"),
+        "@zenginui/mcp": z("mcp"),
+        typescript: VERSIONS.typescript,
+        ...(!next || opts.storybook ? { vite: VERSIONS.vite } : {}),
+        ...(opts.storybook
+            ? {
+                storybook: VERSIONS.storybook,
+                "@storybook/react-vite": VERSIONS["@storybook/react-vite"],
+                "@storybook/addon-docs": VERSIONS["@storybook/addon-docs"],
+                "@storybook/addon-a11y": VERSIONS["@storybook/addon-a11y"],
+            }
+            : {}),
+        ...opts.install.devDependencies,
+    });
+    const scripts = {
+        dev: next ? "zengin tokens && next dev" : "zengin tokens && vite",
+        build: next ? "zengin tokens && next build" : "zengin tokens && tsc -p tsconfig.json --noEmit && vite build",
+        ...(next ? { start: "next start" } : { preview: "vite preview" }),
+        tokens: "zengin tokens",
+        check: "zengin check",
+        add: "zengin add",
+        ...(opts.mock ? { mock: "zengin mock --schema mock.json" } : {}),
+        ...(opts.storybook ? { storybook: "zengin tokens && storybook dev -p 6006 --no-open", "build-storybook": "zengin tokens && storybook build" } : {}),
+    };
+    return JSON.stringify({ name: opts.name, private: true, version: "0.1.0", type: "module", scripts, dependencies, devDependencies }, null, 2) + "\n";
+}
+function sortKeys(o) {
+    return Object.fromEntries(Object.entries(o).sort(([a], [b]) => a.localeCompare(b)));
+}
+function basename(p) {
+    return p.replace(/[\\/]+$/, "").split(/[\\/]/).pop() ?? p;
+}
+const INDEX_HTML = (name) => `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>${name}</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>
+`;
+const MAIN_TSX = `import "./styles/index.css";
+import "./theme/brand.css";
+import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+import { App } from "./App";
+
+createRoot(document.getElementById("root")!).render(
+  <StrictMode>
+    <App />
+  </StrictMode>,
+);
+`;
+const BRAND_CSS = `/*
+ * Your brand, as token overrides. This is the one file in the project that may hold literals
+ * (scope.foundations in zengin.config.yaml). Redefine tokens the system already has and every
+ * component wears the result; there is nothing to change in src/components/ui.
+ *
+ * The full token list is zengin/tokens.json. Run \`zengin tokens\` (dev and build do it for you)
+ * to regenerate src/styles/generated/tokens.css after editing the JSON.
+ */
+
+:root,
+[data-theme="light"] {
+  /* --color-primary: #1B3FE4; */
+  /* --font-display: "Archivo", sans-serif; */
+  /* --radius-md: 0px; */
+}
+
+[data-theme="dark"] {
+  /* --color-primary: #7B90FF; */
+}
+`;
+const VITE_CONFIG = `import react from "@vitejs/plugin-react";
+import { defineConfig } from "vite";
+
+// "@" is src, matching tsconfig paths. A root-relative alias needs no Node imports, so the config typechecks without @types/node.
+export default defineConfig({
+  plugins: [react()],
+  resolve: { alias: { "@": "/src" } },
+});
+`;
+const TSCONFIG = (storybook) => JSON.stringify({
+    compilerOptions: {
+        target: "ES2022",
+        module: "ESNext",
+        moduleResolution: "Bundler",
+        lib: ["ES2022", "DOM", "DOM.Iterable"],
+        jsx: "react-jsx",
+        strict: true,
+        noUncheckedIndexedAccess: true,
+        isolatedModules: true,
+        skipLibCheck: true,
+        resolveJsonModule: true,
+        noEmit: true,
+        types: ["vite/client"],
+        baseUrl: ".",
+        paths: { "@/*": ["./src/*"] },
+    },
+    include: ["src", "vite.config.ts", ...(storybook ? ["stories", ".storybook"] : [])],
+}, null, 2) + "\n";
+const GITIGNORE = `node_modules/
+dist/
+storybook-static/
+# Built from zengin/tokens*.json by \`zengin tokens\`
+src/styles/generated/
+`;
+const ZENGIN_CONFIG = (version) => `# The components in src/components/ui are this project's design system. The definitions the engine
+# enforces against live in zengin/. Every rule is on; relax one here rather than around it.
+system:
+  package: "${LAYOUT.alias}"
+  version: "${version}"           # the Zengin UI version the components were copied from
+  definitions: ./${LAYOUT.definitionsDir}
+
+scope:
+  include: ["src/**/*.{ts,tsx,css}"]
+  foundations: ["src/theme/**", "src/styles/**"]   # literals live here and nowhere else
+  ownership: ["${LAYOUT.componentsDir}/**", "${LAYOUT.libDir}/**"]   # yours; the foundation rules still apply inside
+
+rules:
+  color-literal: { severity: error, allow: semantic }
+  spacing-literal: error
+  token-reference: error
+  unknown-prop: error
+  unknown-prop-value: error
+  classname-policy: error
+  component-substitution: error
+`;
+const MCP_JSON = `{
+  "mcpServers": {
+    "zengin": {
+      "command": "zengin-mcp",
+      "env": { "ZENGIN_CONFIG": "zengin.config.yaml" }
+    }
+  }
+}
+`;
+const CLAUDE_SETTINGS = `{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit|MultiEdit",
+        "hooks": [{ "type": "command", "command": "zengin-hook", "timeout": 30, "statusMessage": "Checking against the design system..." }]
+      }
+    ]
+  }
+}
+`;
+const STORYBOOK_MAIN = `import type { StorybookConfig } from "@storybook/react-vite";
+
+const config: StorybookConfig = {
+  framework: "@storybook/react-vite",
+  stories: ["../stories/**/*.stories.tsx"],
+  addons: ["@storybook/addon-docs", "@storybook/addon-a11y"],
+  core: { disableTelemetry: true },
+};
+
+export default config;
+`;
+const STORYBOOK_PREVIEW = `import type { Decorator, Preview } from "@storybook/react-vite";
+import "../src/styles/index.css";
+import "../src/theme/brand.css";
+
+/** Every story renders inside a themed surface. The toolbar switches data-theme, as a consumer would. */
+const withTheme: Decorator = (Story, context) => {
+  const theme = (context.globals["theme"] as string) ?? "light";
+  return (
+    <div data-theme={theme} style={{ minHeight: "100%", padding: "var(--spacing-6)", background: "var(--color-surface)", color: "var(--color-text)", fontFamily: "var(--font-sans)" }}>
+      <Story />
+    </div>
+  );
+};
+
+const preview: Preview = {
+  globalTypes: {
+    theme: {
+      description: "Theme",
+      toolbar: { title: "Theme", icon: "mirror", items: [{ value: "light", title: "Light" }, { value: "dark", title: "Dark" }], dynamicTitle: true },
+    },
+  },
+  initialGlobals: { theme: "light" },
+  decorators: [withTheme],
+  parameters: { backgrounds: { disable: true }, controls: { expanded: true }, a11y: { test: "error" } },
+};
+
+export default preview;
+`;
+const STORIES_MANIFEST = `import manifests from "../${LAYOUT.definitionsDir}/components.json";
+
+/** The manifest the engine enforces against. Stories read it, so controls and variant matrices cannot drift from it. */
+interface Prop {
+  type: string;
+  values?: string[];
+  default?: unknown;
+}
+
+interface Manifest {
+  name: string;
+  props?: Record<string, Prop>;
+  className?: { allow?: string[] };
+}
+
+const byName = new Map((manifests as unknown as Manifest[]).map((m) => [m.name, m]));
+
+export function manifest(name: string): Manifest {
+  const m = byName.get(name);
+  if (!m) throw new Error(\`No manifest for \${name}\`);
+  return m;
+}
+
+/** Enum values for a prop, in manifest order. */
+export function values(component: string, prop: string): string[] {
+  const p = manifest(component).props?.[prop];
+  if (!p?.values) throw new Error(\`\${component}.\${prop} is not an enum prop\`);
+  return p.values;
+}
+
+/** Storybook argTypes for every enum and boolean prop the manifest declares. */
+export function argTypesFor(component: string): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const [name, p] of Object.entries(manifest(component).props ?? {})) {
+    if (p.type === "enum") out[name] = { control: "select", options: p.values, table: { defaultValue: p.default === undefined ? undefined : { summary: String(p.default) } } };
+    else if (p.type === "boolean") out[name] = { control: "boolean" };
+    else if (p.type === "number") out[name] = { control: "number" };
+    else if (p.type === "string") out[name] = { control: "text" };
+    else out[name] = { control: false };
+  }
+  return out;
+}
+
+/** What className may set, for the docs description. */
+export function classNameAllow(component: string): string {
+  const allow = manifest(component).className?.allow ?? [];
+  return allow.length ? \`className may set: \${allow.join(", ")}.\` : "className is not a styling API on this component.";
+}
+`;
+const README = (name, template, components, framework = "vite") => `# ${name}
+
+Created with \`zengin create\` from the **${template}** template${framework === "next" ? ", on Next.js (App Router, \`src/app\`)" : ""}. The components in \`src/components/ui\` are yours: edit them, the engine keeps everything else on the system they define.
+
+\`\`\`bash
+npm install
+npm run dev          # http://localhost:${framework === "next" ? "3000" : "5173"}
+npm run storybook    # http://localhost:6006
+npm run check        # zengin check: every file in src against zengin/
+npm run add -- select switch   # more components from the registry
+\`\`\`
+
+## Where things are
+
+| Path | What |
+| --- | --- |
+| \`src/components/ui/\` | ${components.join(", ")}. Each file carries a \`zengin-owned\` pragma with the version it was copied from, so a rollup can tell how far it has drifted. |
+| \`zengin/\` | \`tokens.json\`, \`tokens.dark.json\`, \`components.json\`: the definitions the engine enforces against. |
+| \`src/theme/brand.css\` | Your brand as token overrides. The one place literals are allowed. |
+| \`src/styles/\` | The base stylesheet and the component imports. \`generated/tokens.css\` is built by \`zengin tokens\`. |
+| \`zengin.config.yaml\` | The policy. Every rule at error. |
+| \`.mcp.json\`, \`.claude/settings.json\` | The MCP server and the edit hook, so agents working here are checked as they write. |
+`;
+const NEXT_CONFIG = `import type { NextConfig } from "next";
+
+// "@" is src through tsconfig paths; Next reads them. Nothing else to configure.
+const config: NextConfig = { reactStrictMode: true };
+
+export default config;
+`;
+/** The template's App, mounted on the client. The templates read window and document in hooks, which is what an SPA does; ssr: false keeps that honest. */
+const NEXT_PAGE = `"use client";
+import dynamic from "next/dynamic";
+
+const App = dynamic(() => import("@/App").then((m) => m.App), { ssr: false });
+
+export default function Page() {
+  return <App />;
+}
+`;
+/**
+ * The root layout from the template's index.html and main.tsx: the same stylesheet imports (the tokens,
+ * the brand, the template's own css), the title as metadata, and a <head> with the fonts link so that
+ * `zengin theme`, `zengin fonts` and `zengin brand` patch it the way they patch index.html.
+ */
+const NEXT_LAYOUT = (opts) => {
+    const title = /<title>([^<]*)<\/title>/.exec(opts.html)?.[1]?.trim() || opts.name;
+    // A stylesheet link in a React 19 layout needs `precedence`, or Next's prerender fails on the hoisting; the patchers add it too.
+    const links = [...opts.html.matchAll(/<link[^>]*rel="(?:stylesheet|preconnect)"[^>]*>/g)].map((m) => m[0]
+        .replace(/\s*\/?>$/, " />")
+        .replace(/\scrossorigin(?=\s|\/|>)/, " crossOrigin=\"anonymous\"")
+        .replace(/(rel="stylesheet"[^>]*?)\s\/>$/, '$1 precedence="default" />'));
+    const imports = [...opts.main.matchAll(/^import "(\.\/[^"]+\.css)";$/gm)].map((m) => m[1].replace(/^\.\//, "@/"));
+    const css = (imports.length ? imports : ["@/styles/index.css", "@/theme/brand.css"]).map((p) => `import "${p}";`).join("\n");
+    return `${css}
+import type { Metadata } from "next";
+import type { ReactNode } from "react";
+
+export const metadata: Metadata = { title: ${JSON.stringify(title)} };
+
+export default function RootLayout({ children }: { children: ReactNode }) {
+  return (
+    <html lang="en" suppressHydrationWarning>
+      <head>
+${links.map((l) => `        ${l}`).join("\n")}
+      </head>
+      <body>{children}</body>
+    </html>
+  );
+}
+`;
+};
+const TSCONFIG_NEXT = (storybook) => JSON.stringify({
+    compilerOptions: {
+        target: "ES2022",
+        module: "ESNext",
+        moduleResolution: "Bundler",
+        lib: ["ES2022", "DOM", "DOM.Iterable"],
+        jsx: "react-jsx",
+        strict: true,
+        noUncheckedIndexedAccess: true,
+        isolatedModules: true,
+        skipLibCheck: true,
+        resolveJsonModule: true,
+        esModuleInterop: true,
+        allowJs: true,
+        incremental: true,
+        noEmit: true,
+        plugins: [{ name: "next" }],
+        baseUrl: ".",
+        paths: { "@/*": ["./src/*"] },
+    },
+    include: ["next-env.d.ts", "src", ".next/types/**/*.ts", ".next/dev/types/**/*.ts", ...(storybook ? ["stories", ".storybook"] : [])],
+    exclude: ["node_modules"],
+}, null, 2) + "\n";

package/dist/fonts.d.ts

@@ -0,0 +1,42 @@
+import type { RegistrySource } from "./load.js";
+import type { FontPairing } from "./schema.js";
+/**
+ * A pairing is three roles, display, text and code, each a Google Fonts family at the weights the
+ * components use. Applying one touches exactly what a theme touches for fonts: the three font tokens
+ * in src/theme/brand.css and the one fonts link in index.html. The palette, radii and shadows stay.
+ */
+export interface FontsSummary {
+    name: string;
+    title: string;
+    description: string;
+    pairing: FontPairing;
+}
+export interface ApplyFontsResult {
+    name: string;
+    pairing: FontPairing;
+    /** Project-relative paths written. */
+    files: string[];
+    html: boolean;
+    /** With selfHost: the font files downloaded into public/fonts. */
+    downloaded: string[];
+}
+export declare const FALLBACK_SANS = "ui-sans-serif, system-ui, -apple-system, \"Segoe UI\", Roboto, sans-serif";
+export declare const FALLBACK_SERIF = "ui-serif, Georgia, \"Times New Roman\", serif";
+export declare const FALLBACK_MONO = "ui-monospace, SFMono-Regular, Menlo, Consolas, monospace";
+export declare function listFonts(source: RegistrySource): Promise<FontsSummary[]>;
+/** `Family:400;700` for the fonts link: each role at its own weights. */
+export declare function pairingFamilies(p: FontPairing): string[];
+/** The three token declarations a pairing sets, with the fallback stack each role deserves. */
+export declare function pairingCss(p: FontPairing): Record<"--font-sans" | "--font-display" | "--font-mono", string>;
+/**
+ * Rewrites the font tokens in a brand file. Each declaration is replaced where it is (every block that
+ * sets it, so light and dark agree) or added to the first block when the file never set it.
+ */
+export declare function applyPairingToCss(css: string, p: FontPairing): string;
+export declare function applyFonts(opts: {
+    projectDir: string;
+    name: string;
+    source: RegistrySource;
+    selfHost?: boolean;
+    fetcher?: typeof fetch;
+}): Promise<ApplyFontsResult>;

package/dist/fonts.js

@@ -0,0 +1,132 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fontsHref, patchIndexHtml } from "./html.js";
+/** Registry items are `fonts-<name>`, so a pairing and a theme can share a name; people say the bare name. */
+const bare = (name) => name.replace(/^fonts-/, "");
+export const FALLBACK_SANS = "ui-sans-serif, system-ui, -apple-system, \"Segoe UI\", Roboto, sans-serif";
+export const FALLBACK_SERIF = "ui-serif, Georgia, \"Times New Roman\", serif";
+export const FALLBACK_MONO = "ui-monospace, SFMono-Regular, Menlo, Consolas, monospace";
+export async function listFonts(source) {
+    const index = await source.index();
+    return index.items.filter((i) => i.type === "fonts" && i.pairing).map((i) => ({ name: bare(i.name), title: i.title, description: i.description, pairing: i.pairing }));
+}
+/** `Family:400;700` for the fonts link: each role at its own weights. */
+export function pairingFamilies(p) {
+    const roles = [p.display, p.sans, p.mono];
+    const out = [];
+    for (const r of roles) {
+        const spec = `${r.family}:${r.weights.join(";")}`;
+        if (!out.includes(spec))
+            out.push(spec);
+    }
+    return out;
+}
+/** The three token declarations a pairing sets, with the fallback stack each role deserves. */
+export function pairingCss(p) {
+    const stack = (family, serif, then) => `"${family}", ${then ? `"${then}", ` : ""}${serif ? FALLBACK_SERIF : FALLBACK_SANS}`;
+    return {
+        "--font-sans": stack(p.sans.family, p.sans.serif),
+        "--font-display": p.display.family === p.sans.family ? stack(p.display.family, p.display.serif) : stack(p.display.family, p.display.serif, p.sans.family),
+        "--font-mono": `"${p.mono.family}", ${FALLBACK_MONO}`,
+    };
+}
+/**
+ * Rewrites the font tokens in a brand file. Each declaration is replaced where it is (every block that
+ * sets it, so light and dark agree) or added to the first block when the file never set it.
+ */
+export function applyPairingToCss(css, p) {
+    let out = css;
+    const missing = [];
+    for (const [prop, value] of Object.entries(pairingCss(p))) {
+        const re = new RegExp(`(^[ \\t]*)${prop}\\s*:[^;]*;`, "gm");
+        if (re.test(out))
+            out = out.replace(re, `$1${prop}: ${value};`);
+        else
+            missing.push(`  ${prop}: ${value};`);
+    }
+    if (missing.length) {
+        const open = /(:root[^{]*\{[ \t]*\r?\n)/.exec(out);
+        out = open ? out.replace(open[0], `${open[0]}${missing.join("\n")}\n`) : `:root {\n${missing.join("\n")}\n}\n\n${out}`;
+    }
+    return out;
+}
+export async function applyFonts(opts) {
+    const dir = resolve(opts.projectDir);
+    if (!existsSync(join(dir, "zengin.config.yaml")))
+        throw new Error(`${dir} has no zengin.config.yaml. Run zengin fonts inside a project made by zengin create, or pass --dir.`);
+    const index = await opts.source.index();
+    const summary = index.items.find((i) => i.name === `fonts-${bare(opts.name)}` && i.type === "fonts");
+    if (!summary) {
+        const names = index.items.filter((i) => i.type === "fonts").map((i) => bare(i.name));
+        throw new Error(`No pairing "${opts.name}". Pairings: ${names.join(", ")}.`);
+    }
+    const item = await opts.source.item(summary.name);
+    const pairing = item.pairing;
+    if (!pairing)
+        throw new Error(`The registry item "${opts.name}" carries no pairing.`);
+    const files = [];
+    const brand = join(dir, "src", "theme", "brand.css");
+    const before = existsSync(brand) ? readFileSync(brand, "utf8") : `/* Fonts, set by zengin fonts. */\n\n:root {\n}\n`;
+    mkdirSync(dirname(brand), { recursive: true });
+    writeFileSync(brand, applyPairingToCss(before, pairing));
+    files.push("src/theme/brand.css");
+    const families = pairingFamilies(pairing);
+    let downloaded = [];
+    let html;
+    if (opts.selfHost) {
+        const hosted = await selfHost(dir, families, opts.fetcher ?? fetch);
+        downloaded = hosted.downloaded;
+        files.push(hosted.cssFile);
+        if (hosted.mainPatched)
+            files.push(hosted.mainPatched);
+        html = patchIndexHtml(dir, { fonts: null });
+    }
+    else {
+        html = patchIndexHtml(dir, { fonts: fontsHref(families) });
+    }
+    if (html)
+        files.push("index.html");
+    return { name: bare(item.name), pairing, files, html, downloaded };
+}
+/**
+ * Downloads the woff2 files Google serves for the families into public/fonts and writes the @font-face
+ * rules to src/theme/fonts.css, imported from main.tsx, so nothing loads from fonts.googleapis.com at
+ * runtime. Google's CSS is fetched with a modern browser's user agent, which is what makes it answer
+ * with woff2 and unicode ranges.
+ */
+async function selfHost(dir, families, fetcher) {
+    const href = fontsHref(families);
+    const ua = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/125.0 Safari/537.36";
+    const res = await fetcher(href, { headers: { "user-agent": ua } });
+    if (!res.ok)
+        throw new Error(`Google Fonts answered ${res.status} for ${href}`);
+    let css = await res.text();
+    const fontsDir = join(dir, "public", "fonts");
+    mkdirSync(fontsDir, { recursive: true });
+    const downloaded = [];
+    const urls = [...new Set([...css.matchAll(/url\((https:\/\/fonts\.gstatic\.com\/[^)]+)\)/g)].map((m) => m[1]))];
+    for (const url of urls) {
+        const name = url.split("/").slice(-2).join("-").replace(/[^A-Za-z0-9._-]/g, "");
+        const file = join(fontsDir, name);
+        const r = await fetcher(url);
+        if (!r.ok)
+            throw new Error(`Google Fonts answered ${r.status} for ${url}`);
+        writeFileSync(file, Buffer.from(await r.arrayBuffer()));
+        downloaded.push(`public/fonts/${name}`);
+        css = css.split(url).join(`/fonts/${name}`);
+    }
+    const cssFile = "src/theme/fonts.css";
+    writeFileSync(join(dir, cssFile), `/* Self-hosted by zengin fonts --self-host: ${families.join(", ")}. Files in public/fonts. */\n\n${css.trim()}\n`);
+    let mainPatched = null;
+    const main = join(dir, "src", "main.tsx");
+    if (existsSync(main)) {
+        const src = readFileSync(main, "utf8");
+        if (!src.includes('"./theme/fonts.css"')) {
+            const anchor = 'import "./theme/brand.css";';
+            const next = src.includes(anchor) ? src.replace(anchor, `${anchor}\nimport "./theme/fonts.css";`) : `import "./theme/fonts.css";\n${src}`;
+            writeFileSync(main, next);
+            mainPatched = "src/main.tsx";
+        }
+    }
+    return { cssFile, downloaded, mainPatched };
+}

package/dist/html.d.ts

@@ -0,0 +1,16 @@
+export interface HtmlPatch {
+    title?: string;
+    themeColor?: string;
+    /** href for the icon link. */
+    icon?: string;
+    /** Google Fonts stylesheet href; null removes the one a theme or brand added before. */
+    fonts?: string | null;
+}
+/**
+ * Edits index.html in place: the title, the theme-color meta, the icon, and one fonts link the CLI owns
+ * (marked with data-zengin so a later theme replaces it, never duplicates it). Returns false when there
+ * is no index.html to patch.
+ */
+export declare function patchIndexHtml(projectDir: string, patch: HtmlPatch): boolean;
+/** The Google Fonts css2 href for the families, at the four weights components use unless `Family:400;700` pins them. */
+export declare function fontsHref(families: string[]): string;