@kinetixui/cli 0.23.2 → 0.24.0

package/README.md

@@ -0,0 +1,89 @@
+# @kinetixui/cli
+
+Adds KinetixUI components and tokens to your project by writing source into your repo — the
+copy-the-code model, not a dependency you import from.
+
+**Beta.** Ships alongside `@kinetixui/ui` and `@kinetixui/tokens` on one version line.
+
+```bash
+npx @kinetixui/cli init
+npx @kinetixui/cli add button card dialog
+```
+
+No install step is needed; `npx` is the intended way to run it. The binary is `kinetixui` if you do
+install it.
+
+## What it is
+
+A registry client and a code writer. `init` sets up `kinetixui.json` and writes the token contract into
+your global stylesheet. `add` resolves a component's registry dependencies, installs the npm packages it
+needs with *your* package manager, and writes the component source into your tree. From that point the
+code is yours to edit — nothing rewrites it unless you ask.
+
+## Commands
+
+| Command | Does |
+| --- | --- |
+| `init` | Create `kinetixui.json`, write `:root` / `.dark` token blocks into your stylesheet |
+| `add <name…>` | Resolve and write component source, plus its registry and npm dependencies |
+| `list` | List what the registry offers |
+| `inspect <name>` | Show a component's files, dependencies and registry metadata |
+| `parity <name>` | Show which platforms carry a component, and why one does not |
+| `lint` | Check your usage against the token contract |
+| `doctor` | Check that your project is set up correctly |
+| `theme` | Work with themes |
+| `preset` | Read a Kinetix Create preset code (`KX1_…`) and emit CSS or native token files |
+| `create` | Scaffolding helpers |
+
+Run any command with `--help` for its flags. Full reference: <https://kinetixui.com/docs/cli>.
+
+## Where components come from
+
+`add` fetches from a registry over HTTPS. The default is `https://kinetixui.com/r`, which serves a
+shadcn-compatible JSON descriptor per component. You can point it elsewhere:
+
+```bash
+npx @kinetixui/cli add button --registry https://your-mirror.example.com/r
+```
+
+`-r, --registry <url>` is accepted by `init`, `add`, `list` and `inspect`. To set it once for a project
+instead of on every command, put it in `kinetixui.json`:
+
+```json
+{
+  "registry": "https://your-mirror.example.com/r"
+}
+```
+
+The flag wins when both are present. The URL is validated before use, and component names are validated
+against a strict character set before they are used to build any path — a registry response cannot direct
+the CLI to write outside your project.
+
+**One consequence to be aware of:** `add` needs that origin to be reachable, and there is no offline
+mode. If your builds cannot depend on `kinetixui.com`, mirror the registry JSON and set `registry` in
+`kinetixui.json`. When the registry is unreachable the CLI says so and names both ways to point
+elsewhere, rather than failing with a bare network error.
+
+## Requirements
+
+- **Node 18 or newer** (declared in `engines`)
+- A JavaScript package manager on `PATH` — npm, pnpm, yarn or bun; the CLI detects which you use and
+  calls it rather than assuming npm
+- A project with a global stylesheet for `init` to write into
+
+## What it does not do
+
+It does not publish, does not phone home, and does not write outside the directory you run it in. It
+installs dependencies by invoking your package manager, so anything it installs is visible in your
+lockfile like any other dependency.
+
+## Links
+
+- CLI reference — <https://kinetixui.com/docs/cli>
+- Installation — <https://kinetixui.com/docs/installation>
+- Components — <https://kinetixui.com/components>
+- Source — <https://github.com/zedalleys/kinetixui>
+
+## License
+
+MIT

package/dist/index.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 
-// src/index.ts
+// src/program.ts
 import { Command } from "commander";
 import pc10 from "picocolors";
 
@@ -39,6 +39,11 @@ async function readConfig(cwd) {
 async function writeConfig(cwd, config) {
   await writeFile(path.join(cwd, CONFIG_FILE), JSON.stringify(config, null, 2) + "\n", "utf8");
 }
+async function resolveRegistry(cwd, fromFlag) {
+  if (fromFlag && fromFlag !== DEFAULT_REGISTRY) return fromFlag;
+  const config = await readConfig(cwd);
+  return config?.registry?.trim() || DEFAULT_REGISTRY;
+}
 function resolveAliasDir(cwd, config, alias) {
   const raw = config.aliases[alias].replace(/^@\//, "");
   return path.join(cwd, config.srcDir ? "src" : "", raw);
@@ -147,13 +152,49 @@ function runInstall(cwd, pm, packages) {
 }
 
 // src/lib/registry.ts
+async function request(url) {
+  try {
+    return await fetch(url);
+  } catch (cause) {
+    const origin = safeOrigin(url);
+    throw new Error(
+      `Could not reach the registry at ${origin} (${cause.message}). Check the network, or point somewhere else with --registry <url> or "registry" in kinetixui.json.`,
+      { cause }
+    );
+  }
+}
+function safeOrigin(url) {
+  try {
+    return new URL(url).origin;
+  } catch {
+    return url;
+  }
+}
+async function parse(res, url, describe, valid) {
+  let data;
+  try {
+    data = await res.json();
+  } catch (cause) {
+    throw new Error(
+      `The registry at ${safeOrigin(url)} did not return JSON for ${describe} (${cause.message}). If you are behind a proxy, it may be answering instead of the registry.`,
+      { cause }
+    );
+  }
+  if (!valid(data)) {
+    throw new Error(`The registry at ${safeOrigin(url)} returned JSON that is not a valid ${describe} (${url}).`);
+  }
+  return data;
+}
+var isIndex = (v) => typeof v === "object" && v !== null && Array.isArray(v.items);
+var isItem = (v) => typeof v === "object" && v !== null && typeof v.name === "string" && Array.isArray(v.files);
+var isSpec = (v) => typeof v === "object" && v !== null && typeof v.name === "string";
 async function fetchRegistryIndex(registryUrl) {
   const url = `${assertRegistryUrl(registryUrl).replace(/\/$/, "")}/registry.json`;
-  const res = await fetch(url);
+  const res = await request(url);
   if (!res.ok) {
     throw new Error(`Could not load the registry index (${res.status} at ${url}).`);
   }
-  const data = await res.json();
+  const data = await parse(res, url, "registry index", isIndex);
   return data.items;
 }
 async function fetchComponentNames(registryUrl) {
@@ -163,22 +204,22 @@ async function fetchComponentNames(registryUrl) {
 async function fetchRegistryItem(registryUrl, name) {
   const base = assertRegistryUrl(registryUrl).replace(/\/$/, "");
   const url = `${base}/${assertComponentName(name)}.json`;
-  const res = await fetch(url);
+  const res = await request(url);
   if (!res.ok) {
     throw new Error(`Could not find "${name}" in the registry (${res.status} at ${url}).`);
   }
-  return await res.json();
+  return await parse(res, url, `registry item for "${name}"`, isItem);
 }
 async function fetchComponentSpec(registryUrl, name) {
   const base = assertRegistryUrl(registryUrl).replace(/\/$/, "");
   const specsBase = base.endsWith("/r") ? `${base.slice(0, -2)}/specs` : `${base}/specs`;
   const url = `${specsBase}/${assertComponentName(name)}.json`;
-  const res = await fetch(url);
+  const res = await request(url);
   if (res.status === 404) return null;
   if (!res.ok) {
     throw new Error(`Could not load the component spec for "${name}" (${res.status} at ${url}).`);
   }
-  return await res.json();
+  return await parse(res, url, `component spec for "${name}"`, isSpec);
 }
 async function resolveTree(registryUrl, names) {
   const resolved = /* @__PURE__ */ new Map();
@@ -199,17 +240,18 @@ async function resolveTree(registryUrl, names) {
 async function add(names, options) {
   const cwd = process.cwd();
   const config = await readConfig(cwd) ?? DEFAULT_CONFIG;
+  const registry = await resolveRegistry(cwd, options.registry);
   if (!existsSync4(path4.join(cwd, CONFIG_FILE))) {
     console.log(pc.yellow("!"), `No ${CONFIG_FILE} found \u2014 using defaults. Run "kinetixui init" first to set your own aliases.`);
   }
   if (options.all) {
     console.log("Fetching the full component list\u2026");
-    names = await fetchComponentNames(options.registry);
+    names = await fetchComponentNames(registry);
   } else if (names.length === 0) {
     throw new Error('Pass component names to add (e.g. "kinetixui add button card"), or use --all for every component.');
   }
   console.log(options.all ? `Resolving all ${names.length} components\u2026` : `Resolving ${names.join(", ")}\u2026`);
-  const items = await resolveTree(options.registry, names);
+  const items = await resolveTree(registry, names);
   const { deps, written, skipped } = await writeItems(cwd, config, items.values(), options.overwrite);
   for (const file of written) console.log(pc.green("\u2714"), `Added ${file}`);
   for (const file of skipped) console.log(pc.yellow("skip"), `${file} already exists (pass --overwrite to replace it)`);
@@ -270,13 +312,15 @@ async function doctor() {
       levels.push(report("warn", `Tailwind CSS file not found at ${path5.relative(cwd, cssPath2)} \u2014 the token contract has nowhere to land.`));
     }
   }
+  const registry = await resolveRegistry(cwd);
+  const origin = registry === DEFAULT_REGISTRY ? registry : `${registry} (from ${CONFIG_FILE})`;
   let registryNames = null;
   try {
-    const items = await fetchRegistryIndex(DEFAULT_REGISTRY);
+    const items = await fetchRegistryIndex(registry);
     registryNames = new Set(items.filter((item) => item.type === "registry:ui").map((item) => item.name));
-    levels.push(report("pass", `Registry reachable (${DEFAULT_REGISTRY}) \u2014 ${registryNames.size} component(s) listed.`));
+    levels.push(report("pass", `Registry reachable (${origin}) \u2014 ${registryNames.size} component(s) listed.`));
   } catch (err) {
-    levels.push(report("fail", `Registry unreachable at ${DEFAULT_REGISTRY}: ${err.message}`));
+    levels.push(report("fail", `Registry unreachable at ${origin}: ${err.message}`));
   }
   if (config && registryNames) {
     const uiDir = resolveAliasDir(cwd, config, "ui");
@@ -374,7 +418,7 @@ async function init(options) {
   };
   await writeConfig(cwd, config);
   console.log(pc3.green("\u2714"), `Created ${CONFIG_FILE}`);
-  const items = await resolveTree(options.registry, ["tokens"]);
+  const items = await resolveTree(await resolveRegistry(cwd, options.registry), ["tokens"]);
   const { written, skipped } = await writeItems(cwd, config, items.values(), false);
   for (const file of written) console.log(pc3.green("\u2714"), `Wrote ${file}`);
   for (const file of skipped) {
@@ -390,7 +434,8 @@ import { existsSync as existsSync7 } from "fs";
 import path7 from "path";
 import pc4 from "picocolors";
 async function inspect(name, options) {
-  const item = await fetchRegistryItem(options.registry, name);
+  const registry = await resolveRegistry(process.cwd(), options.registry);
+  const item = await fetchRegistryItem(registry, name);
   console.log(`${pc4.bold(item.title ?? item.name)} ${pc4.dim(`(${item.name})`)}`);
   if (item.description) console.log(item.description);
   console.log();
@@ -420,7 +465,7 @@ async function inspect(name, options) {
   for (const file of item.files) {
     console.log(`  ${file.path} ${pc4.dim("\u2192")} ${file.target}`);
   }
-  const spec = await fetchComponentSpec(options.registry, name);
+  const spec = await fetchComponentSpec(registry, name);
   if (spec) {
     if (spec.since || spec.status) {
       console.log();
@@ -617,7 +662,7 @@ async function lint(targetArg, options) {
 // src/commands/list.ts
 import pc6 from "picocolors";
 async function list(options) {
-  const items = await fetchRegistryIndex(options.registry);
+  const items = await fetchRegistryIndex(await resolveRegistry(process.cwd(), options.registry));
   const components = items.filter((item) => item.type === "registry:ui").sort((a, b) => a.name.localeCompare(b.name));
   console.log(`${components.length} component(s):`);
   console.log();
@@ -1236,6 +1281,7 @@ var tokens = {
     "secondary-foreground": "#465245",
     "muted": "#f6f6f6",
     "muted-foreground": "#6d6d6d",
+    "surface-grouped": "#f6f6f6",
     "accent": "#f0f7ff",
     "accent-foreground": "#1d4ed8",
     "destructive": "#c60a0a",
@@ -1258,7 +1304,8 @@ var tokens = {
       "on-success-container": "#465245",
       "warning": "#f97907",
       "info-container": "#f0f7ff",
-      "on-info-container": "#395a70"
+      "on-info-container": "#395a70",
+      "muted-on-container": "#616161"
     },
     "chart-1": "#1b3c53",
     "chart-2": "#748873",
@@ -1280,6 +1327,8 @@ var tokens = {
     "tertiary-foreground": "#f0f7ff",
     "info": "#57778d",
     "info-foreground": "#f0f7ff",
+    "scrim": "rgba(0, 0, 0, 0.4)",
+    "on-info-container": "#395a70",
     "brand": "#1b3c53",
     "brand-foreground": "#f0f7ff",
     "action": "#1d4ed8",
@@ -1395,40 +1444,40 @@ var tokens = {
     }
   },
   "fontSize": {
-    "display-lg": "57px",
-    "display-md": "45px",
-    "display-sm": "36px",
-    "headline-lg": "32px",
-    "headline-md": "28px",
-    "headline-sm": "24px",
-    "title-lg": "22px",
-    "title-md": "16px",
-    "title-sm": "14px",
-    "title-dialog": "18px",
-    "label-lg": "14px",
-    "label-md": "12px",
-    "label-sm": "11px",
-    "body-lg": "16px",
-    "body-md": "14px",
-    "body-sm": "12px"
+    "display-lg": "3.5625rem",
+    "display-md": "2.8125rem",
+    "display-sm": "2.25rem",
+    "headline-lg": "2rem",
+    "headline-md": "1.75rem",
+    "headline-sm": "1.5rem",
+    "title-lg": "1.375rem",
+    "title-md": "1rem",
+    "title-sm": "0.875rem",
+    "title-dialog": "1.125rem",
+    "label-lg": "0.875rem",
+    "label-md": "0.75rem",
+    "label-sm": "0.6875rem",
+    "body-lg": "1rem",
+    "body-md": "0.875rem",
+    "body-sm": "0.75rem"
   },
   "lineHeight": {
-    "display-lg": "64px",
-    "display-md": "52px",
-    "display-sm": "44px",
-    "headline-lg": "40px",
-    "headline-md": "36px",
-    "headline-sm": "32px",
-    "title-lg": "28px",
-    "title-md": "24px",
-    "title-sm": "20px",
-    "title-dialog": "24px",
-    "label-lg": "20px",
-    "label-md": "16px",
-    "label-sm": "16px",
-    "body-lg": "24px",
-    "body-md": "20px",
-    "body-sm": "16px"
+    "display-lg": "4rem",
+    "display-md": "3.25rem",
+    "display-sm": "2.75rem",
+    "headline-lg": "2.5rem",
+    "headline-md": "2.25rem",
+    "headline-sm": "2rem",
+    "title-lg": "1.75rem",
+    "title-md": "1.5rem",
+    "title-sm": "1.25rem",
+    "title-dialog": "1.5rem",
+    "label-lg": "1.25rem",
+    "label-md": "1rem",
+    "label-sm": "1rem",
+    "body-lg": "1.5rem",
+    "body-md": "1.25rem",
+    "body-sm": "1rem"
   },
   "letterSpacing": {
     "tighter": "-0.25px",
@@ -1515,14 +1564,14 @@ var tokens = {
     ],
     "focus-destructive": [
       {
-        "color": "#ec5047",
+        "color": "#c60a0a",
         "offsetX": "0",
         "offsetY": "0",
         "blur": "0",
         "spread": "1px"
       },
       {
-        "color": "#ec504733",
+        "color": "#c60a0a33",
         "offsetX": "0",
         "offsetY": "0",
         "blur": "0",
@@ -1566,113 +1615,113 @@ var tokens = {
     "display-lg": {
       "fontFamily": "Montserrat, ui-sans-serif, system-ui, sans-serif",
       "fontWeight": "500",
-      "fontSize": "57px",
-      "lineHeight": "64px",
+      "fontSize": "3.5625rem",
+      "lineHeight": "4rem",
       "letterSpacing": "-0.25px"
     },
     "display-md": {
       "fontFamily": "Montserrat, ui-sans-serif, system-ui, sans-serif",
       "fontWeight": "500",
-      "fontSize": "45px",
-      "lineHeight": "52px",
+      "fontSize": "2.8125rem",
+      "lineHeight": "3.25rem",
       "letterSpacing": "0"
     },
     "display-sm": {
       "fontFamily": "Montserrat, ui-sans-serif, system-ui, sans-serif",
       "fontWeight": "400",
-      "fontSize": "36px",
-      "lineHeight": "44px",
+      "fontSize": "2.25rem",
+      "lineHeight": "2.75rem",
       "letterSpacing": "0"
     },
     "headline-lg": {
       "fontFamily": "Montserrat, ui-sans-serif, system-ui, sans-serif",
       "fontWeight": "600",
-      "fontSize": "32px",
-      "lineHeight": "40px",
+      "fontSize": "2rem",
+      "lineHeight": "2.5rem",
       "letterSpacing": "0"
     },
     "headline-md": {
       "fontFamily": "Montserrat, ui-sans-serif, system-ui, sans-serif",
       "fontWeight": "400",
-      "fontSize": "28px",
-      "lineHeight": "36px",
+      "fontSize": "1.75rem",
+      "lineHeight": "2.25rem",
       "letterSpacing": "0"
     },
     "headline-sm": {
       "fontFamily": "Montserrat, ui-sans-serif, system-ui, sans-serif",
       "fontWeight": "400",
-      "fontSize": "24px",
-      "lineHeight": "32px",
+      "fontSize": "1.5rem",
+      "lineHeight": "2rem",
       "letterSpacing": "0"
     },
     "title-lg": {
       "fontFamily": "Montserrat, ui-sans-serif, system-ui, sans-serif",
       "fontWeight": "400",
-      "fontSize": "22px",
-      "lineHeight": "28px",
+      "fontSize": "1.375rem",
+      "lineHeight": "1.75rem",
       "letterSpacing": "0"
     },
     "title-md": {
       "fontFamily": "Montserrat, ui-sans-serif, system-ui, sans-serif",
       "fontWeight": "500",
-      "fontSize": "16px",
-      "lineHeight": "24px",
+      "fontSize": "1rem",
+      "lineHeight": "1.5rem",
       "letterSpacing": "0.15px"
     },
     "title-sm": {
       "fontFamily": "Montserrat, ui-sans-serif, system-ui, sans-serif",
       "fontWeight": "500",
-      "fontSize": "14px",
-      "lineHeight": "20px",
+      "fontSize": "0.875rem",
+      "lineHeight": "1.25rem",
       "letterSpacing": "0.1px"
     },
     "title-dialog": {
       "fontFamily": "Montserrat, ui-sans-serif, system-ui, sans-serif",
       "fontWeight": "600",
-      "fontSize": "18px",
-      "lineHeight": "24px",
+      "fontSize": "1.125rem",
+      "lineHeight": "1.5rem",
       "letterSpacing": "0"
     },
     "label-lg": {
       "fontFamily": "Montserrat, ui-sans-serif, system-ui, sans-serif",
       "fontWeight": "500",
-      "fontSize": "14px",
-      "lineHeight": "20px",
+      "fontSize": "0.875rem",
+      "lineHeight": "1.25rem",
       "letterSpacing": "0.1px"
     },
     "label-md": {
       "fontFamily": "Montserrat, ui-sans-serif, system-ui, sans-serif",
       "fontWeight": "500",
-      "fontSize": "12px",
-      "lineHeight": "16px",
+      "fontSize": "0.75rem",
+      "lineHeight": "1rem",
       "letterSpacing": "0.5px"
     },
     "label-sm": {
       "fontFamily": "Montserrat, ui-sans-serif, system-ui, sans-serif",
       "fontWeight": "500",
-      "fontSize": "11px",
-      "lineHeight": "16px",
+      "fontSize": "0.6875rem",
+      "lineHeight": "1rem",
       "letterSpacing": "0.5px"
     },
     "body-lg": {
       "fontFamily": "Montserrat, ui-sans-serif, system-ui, sans-serif",
       "fontWeight": "400",
-      "fontSize": "16px",
-      "lineHeight": "24px",
+      "fontSize": "1rem",
+      "lineHeight": "1.5rem",
       "letterSpacing": "0.5px"
     },
     "body-md": {
       "fontFamily": "Montserrat, ui-sans-serif, system-ui, sans-serif",
       "fontWeight": "400",
-      "fontSize": "14px",
-      "lineHeight": "20px",
+      "fontSize": "0.875rem",
+      "lineHeight": "1.25rem",
       "letterSpacing": "0.25px"
     },
     "body-sm": {
       "fontFamily": "Montserrat, ui-sans-serif, system-ui, sans-serif",
       "fontWeight": "400",
-      "fontSize": "12px",
-      "lineHeight": "16px",
+      "fontSize": "0.75rem",
+      "lineHeight": "1rem",
       "letterSpacing": "0"
     }
   }
@@ -1691,6 +1740,7 @@ var TOKEN_CONTRACT = [
   { token: "secondary-foreground", light: "#465245", dark: "#e3e7e3" },
   { token: "muted", light: "#f6f6f6", dark: "#102432" },
   { token: "muted-foreground", light: "#6d6d6d", dark: "#92b2c8" },
+  { token: "surface-grouped", light: "#f6f6f6", dark: "#081219", note: "grouped section under a card" },
   { token: "accent", light: "#f0f7ff", dark: "#102432" },
   { token: "accent-foreground", light: "#1d4ed8", dark: "#f0f7ff" },
   { token: "destructive", light: "#c60a0a", dark: "#dd6a6a", note: "darkened for AA" },
@@ -1709,6 +1759,12 @@ var TOKEN_CONTRACT = [
   { token: "link", light: "#1d4ed8", dark: "#60a5fa", note: "defaults to primary" },
   { token: "focus", light: "#1d4ed8", dark: "#60a5fa", note: "defaults to ring" }
 ];
+var ROLE_DEFAULTS = {
+  action: "primary",
+  "action-foreground": "primary-foreground",
+  link: "primary",
+  focus: "ring"
+};
 var RADIUS_STEP_NAMES = ["sm", "md", "lg", "xl"];
 var ELEVATION_STEP_NAMES = ["sm", "md", "lg", "xl"];
 var px = (value) => Number(value.replace("px", ""));
@@ -1842,6 +1898,9 @@ var NEUTRAL_LADDER = {
     card: 1,
     popover: 1,
     muted: 0.975,
+    // The grouped section a card sits on. Light shares `muted`'s step; dark sits between the page and
+    // `card`, because dark `muted` is above `card` and a card on it would read as recessed.
+    "surface-grouped": 0.975,
     border: 0.86,
     input: 0.86,
     "muted-foreground": 0.535,
@@ -1852,6 +1911,7 @@ var NEUTRAL_LADDER = {
     card: 0.22,
     popover: 0.22,
     muted: 0.27,
+    "surface-grouped": 0.19,
     border: 0.4,
     input: 0.4,
     "muted-foreground": 0.72,
@@ -1933,6 +1993,7 @@ var ALIASED_FROM = {
   input: "border"
 };
 var FOREGROUND_OF = Object.fromEntries(CONTRAST_PAIRS);
+var BASE_OF = Object.fromEntries(CONTRAST_PAIRS.map(([base, fg]) => [fg, base]));
 function shippedColorsFor(mode) {
   const out = {};
   for (const row2 of TOKEN_CONTRACT) out[row2.token] = mode === "dark" ? row2.dark : row2.light;
@@ -1963,14 +2024,29 @@ function resolveMode(design, mode) {
   Object.assign(colors, deriveChart(design.chartPalette, design.brand, mode));
   const border = deriveSurfaceBorder(design.surface, mode, colors.border ?? "#000000");
   if (border) colors.border = border;
+  const generatedAction = colors.action;
+  const pinned = design.manualOverrides;
   for (const [token, hex] of Object.entries(design.manualOverrides)) {
     if (hex) colors[token] = hex;
   }
   for (const [base, fg] of Object.entries(FOREGROUND_OF)) {
-    if (design.manualOverrides[base] && !design.manualOverrides[fg]) {
+    if (pinned[base] && !pinned[fg]) {
       colors[fg] = foregroundFor(colors[base]);
     }
   }
+  for (const [role, source] of Object.entries(ROLE_DEFAULTS)) {
+    if (pinned[role]) continue;
+    if (BASE_OF[role] && pinned[BASE_OF[role]]) continue;
+    const sourceMoved = Boolean(pinned[source] || BASE_OF[source] && pinned[BASE_OF[source]]);
+    if (sourceMoved && colors[source]) colors[role] = colors[source];
+  }
+  const action = colors.action ? hexToOklch(colors.action) : null;
+  if (action && colors.action !== generatedAction) {
+    const states = interactionStates(action, mode);
+    colors["action-hover"] = states.hover;
+    colors["action-pressed"] = states.pressed;
+    if (!pinned["action-foreground"] && !pinned["primary-foreground"]) colors["action-foreground"] = states.foreground;
+  }
   return {
     colors,
     radius: deriveRadius(design.radius),
@@ -2027,14 +2103,14 @@ function cssVarOverrides(resolved, base = SHIPPED_THEME.light) {
   return out;
 }
 var varLines = (resolved, base) => Object.entries(cssVarOverrides(resolved, base)).map(([token, value]) => declaration(token, value));
-function exportCss(theme2, options = {}) {
+function exportCss(theme, options = {}) {
   const rootSelector = options.rootSelector ?? ":root";
   const darkSelector = options.darkSelector ?? ".dark";
-  const rootVars = varLines(theme2.light, SHIPPED_THEME.light);
-  const root = [...colorLines(theme2.light, SHIPPED_THEME.light), ...rootVars];
+  const rootVars = varLines(theme.light, SHIPPED_THEME.light);
+  const root = [...colorLines(theme.light, SHIPPED_THEME.light), ...rootVars];
   const dark = [
-    ...colorLines(theme2.dark, SHIPPED_THEME.dark),
-    ...varLines(theme2.dark, SHIPPED_THEME.dark).filter((line) => !rootVars.includes(line))
+    ...colorLines(theme.dark, SHIPPED_THEME.dark),
+    ...varLines(theme.dark, SHIPPED_THEME.dark).filter((line) => !rootVars.includes(line))
   ];
   return [block(rootSelector, root), block(darkSelector, dark)].filter(Boolean).join("\n\n");
 }
@@ -2127,7 +2203,9 @@ var FLUTTER_COLOR_FIELDS = [
   ["info", "info"],
   ["infoForeground", "info-foreground"],
   ["popover", "popover"],
-  ["popoverForeground", "popover-foreground"]
+  ["popoverForeground", "popover-foreground"],
+  ["onInfoContainer", "on-info-container"],
+  ["scrim", "scrim"]
 ];
 var FLUTTER_CHART_STOPS = [1, 2, 3, 4, 5];
 var shippedRef = (appearance, field) => `KinetixColors.${appearance}.${field}`;
@@ -2147,8 +2225,8 @@ function colorSet(mode, appearance) {
   );
   return [...fields, "    chart: <Color>[", ...chart, "    ],"].join("\n");
 }
-function header(symbol, theme2) {
-  const design = theme2.meta.design;
+function header(symbol, theme) {
+  const design = theme.meta.design;
   return [
     "//",
     `// ${symbol} \u2014 a KinetixUI Create theme.`,
@@ -2167,9 +2245,9 @@ function header(symbol, theme2) {
     "// They apply on the web. That is the only thing this file does not carry.",
     "//",
     "// A field written as `KinetixColors.light.\u2026` is one this design did not change, and it keeps",
-    "// following the library. Six of them \u2014 tertiary, tertiaryForeground, info, infoForeground,",
-    "// successForeground and warningForeground \u2014 are always references, because Create does not model",
-    "// those tokens.",
+    "// following the library. Eight of them \u2014 tertiary, tertiaryForeground, info, infoForeground,",
+    "// onInfoContainer, scrim, successForeground and warningForeground \u2014 are always references, because",
+    "// Create does not model those tokens.",
     "//",
     "// These are `static final` rather than `static const`: Dart's constant expressions do not include",
     "// instance field access, so a `static const` could not reference the shipped palette. The theme is",
@@ -2186,12 +2264,12 @@ function header(symbol, theme2) {
     "//"
   ].join("\n");
 }
-function exportFlutter(theme2, options = {}) {
+function exportFlutter(theme, options = {}) {
   const symbol = options.symbol ?? DEFAULT_FLUTTER_SYMBOL;
   const reason = dartSymbolError(symbol);
   if (reason) throw new Error(reason);
   return [
-    header(symbol, theme2),
+    header(symbol, theme),
     "",
     "import 'package:flutter/widgets.dart';",
     "import 'package:kinetix_ui/kinetix_ui.dart';",
@@ -2201,11 +2279,11 @@ function exportFlutter(theme2, options = {}) {
     // `enum` and Compose's `object` express.
     `abstract final class ${symbol} {`,
     "  static final KinetixColors light = KinetixColors(",
-    colorSet(theme2.light, "light"),
+    colorSet(theme.light, "light"),
     "  );",
     "",
     "  static final KinetixColors dark = KinetixColors(",
-    colorSet(theme2.dark, "dark"),
+    colorSet(theme.dark, "dark"),
     "  );",
     "}",
     ""
@@ -2295,7 +2373,9 @@ var COMPOSE_COLOR_FIELDS = [
   ["info", "info"],
   ["infoForeground", "info-foreground"],
   ["popover", "popover"],
-  ["popoverForeground", "popover-foreground"]
+  ["popoverForeground", "popover-foreground"],
+  ["onInfoContainer", "on-info-container"],
+  ["scrim", "scrim"]
 ];
 var COMPOSE_CHART_STOPS = [1, 2, 3, 4, 5];
 var COMPOSE_UNMAPPED_PRESET_ROLES = ["input", "ring"];
@@ -2318,8 +2398,8 @@ function colorSet2(mode, appearance) {
   );
   return [...fields, "        chart = listOf(", ...chart, "        ),"].join("\n");
 }
-function header2(symbol, theme2) {
-  const design = theme2.meta.design;
+function header2(symbol, theme) {
+  const design = theme.meta.design;
   return [
     "//",
     `// ${symbol} \u2014 a KinetixUI Create theme.`,
@@ -2349,15 +2429,15 @@ function header2(symbol, theme2) {
     "//"
   ].join("\n");
 }
-function exportCompose(theme2, options = {}) {
+function exportCompose(theme, options = {}) {
   const symbol = options.symbol ?? DEFAULT_COMPOSE_SYMBOL;
   const reason = kotlinSymbolError(symbol);
   if (reason) throw new Error(reason);
-  const light = colorSet2(theme2.light, "light");
-  const dark = colorSet2(theme2.dark, "dark");
+  const light = colorSet2(theme.light, "light");
+  const dark = colorSet2(theme.dark, "dark");
   const usesColor = `${light}${dark}`.includes("Color(0x");
   return [
-    header2(symbol, theme2),
+    header2(symbol, theme),
     "",
     "package com.kinetixui.create",
     "",
@@ -2468,6 +2548,59 @@ function swiftColor(hex) {
   const [r, g, b] = swiftUiChannels(`#${h}`);
   return `Color(red: ${r}, green: ${g}, blue: ${b})`;
 }
+function swiftShadowColor(hex) {
+  const h = hex.replace("#", "").trim();
+  if (!/^[0-9a-fA-F]{6}([0-9a-fA-F]{2})?$/.test(h)) return null;
+  const base = h.slice(0, 6) === "000000" ? "Color.black" : swiftColor(`#${h.slice(0, 6)}`);
+  if (!base) return null;
+  if (h.length === 6) return base;
+  const alpha = Number((parseInt(h.slice(6, 8), 16) / 255).toFixed(3));
+  return `${base}.opacity(${alpha})`;
+}
+var RADIUS_STEPS2 = ["sm", "md", "lg", "xl"];
+var ELEVATION_STEPS = ["sm", "md", "lg", "xl"];
+var sameLayers = (a, b) => a.length === b.length && a.every((layer, i) => {
+  const other = b[i];
+  return layer.color.toLowerCase() === other.color.toLowerCase() && layer.offsetX === other.offsetX && layer.offsetY === other.offsetY && layer.blur === other.blur && layer.spread === other.spread;
+});
+var swiftLength = (value) => Number(Number(value).toFixed(3));
+function swiftRadii(radius) {
+  if (RADIUS_STEPS2.every((step) => radius[step] === SHIPPED_RADIUS[step])) return "KinetixRadii.default";
+  return [
+    "KinetixRadii(",
+    `        field: ${swiftLength(String(radius.sm))},`,
+    `        control: ${swiftLength(String(radius.md))},`,
+    `        container: ${swiftLength(String(radius.lg))},`,
+    `        surface: ${swiftLength(String(radius.xl))}`,
+    "    )"
+  ].join("\n");
+}
+function swiftElevations(elevation) {
+  if (ELEVATION_STEPS.every((s) => sameLayers(elevation[s], SHIPPED_ELEVATION[s]))) return "KinetixElevations.default";
+  const step = (layers) => {
+    if (layers.length === 0) return ".none";
+    const rendered = layers.map((layer) => {
+      const color = swiftShadowColor(layer.color) ?? "Color.black.opacity(0.05)";
+      return [
+        "            KinetixShadowLayer(",
+        `                color: ${color},`,
+        `                radius: ${swiftLength(layer.blur)},`,
+        `                x: ${swiftLength(layer.offsetX)},`,
+        `                y: ${swiftLength(layer.offsetY)}`,
+        "            ),"
+      ].join("\n");
+    });
+    return ["KinetixElevation([", ...rendered, "        ])"].join("\n");
+  };
+  return [
+    "KinetixElevations(",
+    `        sm: ${step(elevation.sm)},`,
+    `        md: ${step(elevation.md)},`,
+    `        lg: ${step(elevation.lg)},`,
+    `        xl: ${step(elevation.xl)}`,
+    "    )"
+  ].join("\n");
+}
 var SWIFT_COLOR_FIELDS = [
   "primary",
   "primary-foreground",
@@ -2503,7 +2636,9 @@ var SWIFT_COLOR_FIELDS = [
   "info",
   "info-foreground",
   "popover",
-  "popover-foreground"
+  "popover-foreground",
+  "on-info-container",
+  "scrim"
 ];
 var SWIFT_CHART_STOPS = [1, 2, 3, 4, 5];
 var SHIPPED_ENUM = { light: "KinetixColorsSwiftUI", dark: "KinetixColorsSwiftUIDark" };
@@ -2524,8 +2659,8 @@ function colorSet3(mode, appearance) {
   );
   return [...fields, "        chart: [", ...chart, "        ]"].join("\n");
 }
-function header3(symbol, theme2) {
-  const design = theme2.meta.design;
+function header3(symbol, theme) {
+  const design = theme.meta.design;
   return [
     "//",
     `// ${symbol} \u2014 a KinetixUI Create theme.`,
@@ -2534,38 +2669,50 @@ function header3(symbol, theme2) {
     "// editing this file: it is a rendering of a preset, not a source of one.",
     "//",
     `// Theme colour ${design.brand} \xB7 ${design.neutral} neutral \xB7 ${design.chartPalette} charts`,
+    `// Radius ${design.radius} \xB7 surface ${design.surface}`,
+    "//",
+    "// Colours, corner radii and elevation \u2014 the whole design this file can express. Radii and",
+    "// elevation are one value rather than a light/dark pair, because the runtime takes one and the",
+    "// two appearances resolve to the same ladder.",
     "//",
-    "// COLOURS ONLY \u2014 and that is now a limit of this exporter rather than of the package. SwiftUI",
-    "// gained `KinetixRadii` and `KinetixElevations` alongside `KinetixColors`, so there is somewhere",
-    `// for a radius to land; this file does not write one yet. This design's radius (${design.radius}) and`,
-    `// surface treatment (${design.surface}) are therefore NOT carried here \u2014 set them by hand for now:`,
-    "// `KinetixTheme(light: \u2026, dark: \u2026, radii: \u2026, elevations: \u2026)`. Nothing is silently dropped.",
+    "// ONE THING DOES NOT SURVIVE THE PORT. CSS shadows have `spread`; SwiftUI's `.shadow` has no",
+    "// equivalent, so the spread on this design's larger steps is dropped and they render slightly",
+    "// wider here than on the web. The shipped `KinetixElevations.default` is mapped the same way, so",
+    "// a generated theme and the built-in one differ from the web in exactly the same manner.",
     "//",
     "// A field written as `KinetixColorsSwiftUI.\u2026` is one this design did not change, and it keeps",
     "// following the library.",
     "//"
   ].join("\n");
 }
-function exportSwiftUi(theme2, options = {}) {
+function exportSwiftUi(theme, options = {}) {
   const symbol = options.symbol ?? DEFAULT_SWIFT_SYMBOL;
   const reason = swiftSymbolError(symbol);
   if (reason) throw new Error(reason);
   return [
-    header3(symbol, theme2),
+    header3(symbol, theme),
     "",
     "import SwiftUI",
     "import KinetixUI",
     "",
     `public enum ${symbol} {`,
-    "    /// Apply with `KinetixTheme(light: .light, dark: .dark) { \u2026 }`, or set",
-    "    /// `\\.kinetixColors` directly to pin one appearance.",
+    "    /// Apply the whole design with",
+    `    /// \`KinetixTheme(light: .light, dark: .dark, radii: .radii, elevations: .elevations) { \u2026 }\`,`,
+    "    /// or set `\\.kinetixColors` directly to pin one appearance.",
     `    public static let light = KinetixColors(`,
-    colorSet3(theme2.light, "light"),
+    colorSet3(theme.light, "light"),
     "    )",
     "",
     `    public static let dark = KinetixColors(`,
-    colorSet3(theme2.dark, "dark"),
+    colorSet3(theme.dark, "dark"),
     "    )",
+    "",
+    // One value, not a light/dark pair: the runtime takes one, and the resolver produces the same
+    // ladder for both appearances — a card's corner does not change when the lights go out.
+    // `swiftui.test.ts` asserts that equality rather than trusting it.
+    `    public static let radii = ${swiftRadii(theme.light.radius)}`,
+    "",
+    `    public static let elevations = ${swiftElevations(theme.light.elevation)}`,
     "}",
     ""
   ].join("\n");
@@ -2637,7 +2784,10 @@ async function presetSwiftUi(input, opts) {
   const swift = exportSwiftUi(resolveCreateTheme(read(input)), { symbol });
   if (opts.output) {
     await writeFile3(opts.output, swift, "utf8");
-    console.log(pc8.green("\u2714"), `Wrote ${opts.output} \u2014 apply it with KinetixTheme(light: ${symbol}.light, dark: ${symbol}.dark)`);
+    console.log(
+      pc8.green("\u2714"),
+      `Wrote ${opts.output} \u2014 apply it with KinetixTheme(light: ${symbol}.light, dark: ${symbol}.dark, radii: ${symbol}.radii, elevations: ${symbol}.elevations)`
+    );
     return;
   }
   process.stdout.write(swift);
@@ -2886,7 +3036,7 @@ async function themeBuild(name, options) {
 // package.json
 var package_default = {
   name: "@kinetixui/cli",
-  version: "0.23.2",
+  version: "0.24.0",
   description: "Add KinetixUI components and tokens to your project.",
   type: "module",
   license: "MIT",
@@ -2900,8 +3050,10 @@ var package_default = {
   ],
   scripts: {
     build: "tsup src/index.ts --format esm --clean",
-    typecheck: "tsc --noEmit",
-    dev: 'tsup src/index.ts --format esm --watch --onSuccess "node dist/index.js"'
+    dev: 'tsup src/index.ts --format esm --watch --onSuccess "node dist/index.js"',
+    test: "vitest run",
+    "test:watch": "vitest",
+    typecheck: "tsc --noEmit"
   },
   dependencies: {
     commander: "^15.0.0",
@@ -2911,10 +3063,12 @@ var package_default = {
   devDependencies: {
     "@kinetixui/create-preset": "workspace:*",
     "@kinetixui/create-theme": "workspace:*",
-    "@types/node": "^22.20.3",
+    "@types/node": "^22.20.4",
     "@types/prompts": "^2.4.9",
+    jsdom: "^30.1.0",
     tsup: "^8.5.1",
-    typescript: "^5.9.3"
+    typescript: "^5.9.3",
+    vitest: "^5.0.2"
   },
   engines: {
     node: ">=18"
@@ -2925,129 +3079,134 @@ var package_default = {
   }
 };
 
+// src/program.ts
+function createProgram() {
+  const program = new Command();
+  program.name("kinetixui").description("Add KinetixUI components and tokens to your project.").version(package_default.version);
+  program.command("init").description("Set up kinetixui.json and pull in the token contract.").option("-y, --yes", "skip prompts and use defaults", false).option("-r, --registry <url>", "registry base URL", DEFAULT_REGISTRY).action(async (opts) => {
+    try {
+      await init({ registry: opts.registry, yes: opts.yes });
+    } catch (err) {
+      console.error(pc10.red("\u2716"), err.message);
+      process.exitCode = 1;
+    }
+  });
+  program.command("add").description("Add one or more components to your project.").argument("[components...]", "component names, e.g. button card").option("-a, --all", "add every component in the registry", false).option("-o, --overwrite", "overwrite existing files", false).option("-r, --registry <url>", "registry base URL", DEFAULT_REGISTRY).action(async (components, opts) => {
+    try {
+      await add(components, { registry: opts.registry, overwrite: opts.overwrite, all: opts.all });
+    } catch (err) {
+      console.error(pc10.red("\u2716"), err.message);
+      process.exitCode = 1;
+    }
+  });
+  program.command("list").description("List every component available in the registry.").option("-r, --registry <url>", "registry base URL", DEFAULT_REGISTRY).action(async (opts) => {
+    try {
+      await list({ registry: opts.registry });
+    } catch (err) {
+      console.error(pc10.red("\u2716"), err.message);
+      process.exitCode = 1;
+    }
+  });
+  program.command("inspect").description("Show everything the registry knows about one component.").argument("<name>", "component name, e.g. button").option("-r, --registry <url>", "registry base URL", DEFAULT_REGISTRY).action(async (name, opts) => {
+    try {
+      await inspect(name, { registry: opts.registry });
+    } catch (err) {
+      console.error(pc10.red("\u2716"), err.message);
+      process.exitCode = 1;
+    }
+  });
+  program.command("parity").description("Show which platforms carry each component (or one, by name).").argument("[components...]", "component names, e.g. button card \u2014 omit for the full matrix").option("-r, --registry <url>", "registry base URL", DEFAULT_REGISTRY).action(async (components, opts) => {
+    try {
+      await parity(components, { registry: opts.registry });
+    } catch (err) {
+      console.error(pc10.red("\u2716"), err.message);
+      process.exitCode = 1;
+    }
+  });
+  program.command("lint").description("Scan for hardcoded colors and spacing that should be semantic tokens.").argument("[path]", "directory to scan \u2014 defaults to the components/ui aliases from kinetixui.json").option("--no-fail", "exit 0 even if violations are found").action(async (target, opts) => {
+    try {
+      await lint(target, { fail: opts.fail });
+    } catch (err) {
+      console.error(pc10.red("\u2716"), err.message);
+      process.exitCode = 1;
+    }
+  });
+  program.command("doctor").description("Check kinetixui.json, its aliases, and the registry connection.").action(async () => {
+    try {
+      await doctor();
+    } catch (err) {
+      console.error(pc10.red("\u2716"), err.message);
+      process.exitCode = 1;
+    }
+  });
+  const theme = program.command("theme").description("Scaffold and compile a local token override (CSS only \u2014 see 'theme build --help').");
+  theme.command("create").description("Scaffold kinetixui-themes/<name>.csv with every overridable token, commented out.").argument("<name>", "theme name, e.g. acme").option("-f, --force", "overwrite an existing theme file", false).action(async (name, opts) => {
+    try {
+      await themeCreate(name, { force: opts.force });
+    } catch (err) {
+      console.error(pc10.red("\u2716"), err.message);
+      process.exitCode = 1;
+    }
+  });
+  theme.command("build").description("Compile kinetixui-themes/<name>.csv to CSS and print a WCAG AA contrast report. This command is CSS only; native themes come from `preset swiftui|compose|flutter`.").argument("<name>", "theme name, e.g. acme").option("--no-fail-on-contrast", "exit 0 even if a pair fails WCAG AA").action(async (name, opts) => {
+    try {
+      await themeBuild(name, { failOnContrast: opts.failOnContrast });
+    } catch (err) {
+      console.error(pc10.red("\u2716"), err.message);
+      process.exitCode = 1;
+    }
+  });
+  const preset = program.command("preset").description("Read a Kinetix Create preset code (KX1_\u2026) produced by kinetixui.com/create.");
+  preset.command("decode").description("Show what a preset contains. Accepts a KX1_ code or a full /create?preset=\u2026 URL.").argument("<preset>", "a KX1_ code, or a share URL").option("--json", "print the configuration as JSON", false).action((input, opts) => {
+    try {
+      presetDecode(input, { json: opts.json });
+    } catch (err) {
+      console.error(pc10.red("\u2716"), err.message);
+      process.exitCode = 1;
+    }
+  });
+  preset.command("css").description("Resolve a preset into its web CSS override block \u2014 the same output the workspace exports for Web CSS. This command is CSS only; see `preset swiftui|compose|flutter`.").argument("<preset>", "a KX1_ code, or a share URL").option("-o, --output <file>", "write to a file instead of stdout").action(async (input, opts) => {
+    try {
+      await presetCss(input, { output: opts.output });
+    } catch (err) {
+      console.error(pc10.red("\u2716"), err.message);
+      process.exitCode = 1;
+    }
+  });
+  preset.command("swiftui").description("Resolve a preset into a SwiftUI theme file (KinetixColors, light and dark). Colours only \u2014 SwiftUI has no radius or elevation token to carry. No Compose or Flutter output.").argument("<preset>", "a KX1_ code, or a share URL").option("-o, --output <file>", "write to a file instead of stdout").option("-n, --name <symbol>", "the Swift enum to generate", DEFAULT_SWIFT_SYMBOL).action(async (input, opts) => {
+    try {
+      await presetSwiftUi(input, { output: opts.output, name: opts.name });
+    } catch (err) {
+      console.error(pc10.red("\u2716"), err.message);
+      process.exitCode = 1;
+    }
+  });
+  preset.command("compose").description("Resolve a preset into a Jetpack Compose theme file (KinetixColors, light and dark). Colours only \u2014 Compose has no runtime radius or elevation token to carry. No Flutter or Android XML output.").argument("<preset>", "a KX1_ code, or a share URL").option("-o, --output <file>", "write to a file instead of stdout").option("-n, --name <symbol>", "the Kotlin object to generate", DEFAULT_COMPOSE_SYMBOL).action(async (input, opts) => {
+    try {
+      await presetCompose(input, { output: opts.output, name: opts.name });
+    } catch (err) {
+      console.error(pc10.red("\u2716"), err.message);
+      process.exitCode = 1;
+    }
+  });
+  preset.command("flutter").description("Resolve a preset into a Flutter theme file (KinetixColors, light and dark). Colours only \u2014 Flutter's radius and elevation are not runtime-themeable. No Android XML output.").argument("<preset>", "a KX1_ code, or a share URL").option("-o, --output <file>", "write to a file instead of stdout").option("-n, --name <symbol>", "the Dart class to generate", DEFAULT_FLUTTER_SYMBOL).action(async (input, opts) => {
+    try {
+      await presetFlutter(input, { output: opts.output, name: opts.name });
+    } catch (err) {
+      console.error(pc10.red("\u2716"), err.message);
+      process.exitCode = 1;
+    }
+  });
+  preset.command("url").description("Print the canonical share URL for a preset. Prints it \u2014 piping it to your opener is up to you.").argument("<preset>", "a KX1_ code, or a share URL").option("-s, --site <origin>", "site origin", "https://kinetixui.com").action((input, opts) => {
+    try {
+      presetUrlCommand(input, { site: opts.site });
+    } catch (err) {
+      console.error(pc10.red("\u2716"), err.message);
+      process.exitCode = 1;
+    }
+  });
+  return program;
+}
+
 // src/index.ts
-var program = new Command();
-program.name("kinetixui").description("Add KinetixUI components and tokens to your project.").version(package_default.version);
-program.command("init").description("Set up kinetixui.json and pull in the token contract.").option("-y, --yes", "skip prompts and use defaults", false).option("-r, --registry <url>", "registry base URL", DEFAULT_REGISTRY).action(async (opts) => {
-  try {
-    await init({ registry: opts.registry, yes: opts.yes });
-  } catch (err) {
-    console.error(pc10.red("\u2716"), err.message);
-    process.exitCode = 1;
-  }
-});
-program.command("add").description("Add one or more components to your project.").argument("[components...]", "component names, e.g. button card").option("-a, --all", "add every component in the registry", false).option("-o, --overwrite", "overwrite existing files", false).option("-r, --registry <url>", "registry base URL", DEFAULT_REGISTRY).action(async (components, opts) => {
-  try {
-    await add(components, { registry: opts.registry, overwrite: opts.overwrite, all: opts.all });
-  } catch (err) {
-    console.error(pc10.red("\u2716"), err.message);
-    process.exitCode = 1;
-  }
-});
-program.command("list").description("List every component available in the registry.").option("-r, --registry <url>", "registry base URL", DEFAULT_REGISTRY).action(async (opts) => {
-  try {
-    await list({ registry: opts.registry });
-  } catch (err) {
-    console.error(pc10.red("\u2716"), err.message);
-    process.exitCode = 1;
-  }
-});
-program.command("inspect").description("Show everything the registry knows about one component.").argument("<name>", "component name, e.g. button").option("-r, --registry <url>", "registry base URL", DEFAULT_REGISTRY).action(async (name, opts) => {
-  try {
-    await inspect(name, { registry: opts.registry });
-  } catch (err) {
-    console.error(pc10.red("\u2716"), err.message);
-    process.exitCode = 1;
-  }
-});
-program.command("parity").description("Show which platforms carry each component (or one, by name).").argument("[components...]", "component names, e.g. button card \u2014 omit for the full matrix").option("-r, --registry <url>", "registry base URL", DEFAULT_REGISTRY).action(async (components, opts) => {
-  try {
-    await parity(components, { registry: opts.registry });
-  } catch (err) {
-    console.error(pc10.red("\u2716"), err.message);
-    process.exitCode = 1;
-  }
-});
-program.command("lint").description("Scan for hardcoded colors and spacing that should be semantic tokens.").argument("[path]", "directory to scan \u2014 defaults to the components/ui aliases from kinetixui.json").option("--no-fail", "exit 0 even if violations are found").action(async (target, opts) => {
-  try {
-    await lint(target, { fail: opts.fail });
-  } catch (err) {
-    console.error(pc10.red("\u2716"), err.message);
-    process.exitCode = 1;
-  }
-});
-program.command("doctor").description("Check kinetixui.json, its aliases, and the registry connection.").action(async () => {
-  try {
-    await doctor();
-  } catch (err) {
-    console.error(pc10.red("\u2716"), err.message);
-    process.exitCode = 1;
-  }
-});
-var theme = program.command("theme").description("Scaffold and compile a local token override (CSS only \u2014 see 'theme build --help').");
-theme.command("create").description("Scaffold kinetixui-themes/<name>.csv with every overridable token, commented out.").argument("<name>", "theme name, e.g. acme").option("-f, --force", "overwrite an existing theme file", false).action(async (name, opts) => {
-  try {
-    await themeCreate(name, { force: opts.force });
-  } catch (err) {
-    console.error(pc10.red("\u2716"), err.message);
-    process.exitCode = 1;
-  }
-});
-theme.command("build").description("Compile kinetixui-themes/<name>.csv to CSS and print a WCAG AA contrast report. This command is CSS only; native themes come from `preset swiftui|compose|flutter`.").argument("<name>", "theme name, e.g. acme").option("--no-fail-on-contrast", "exit 0 even if a pair fails WCAG AA").action(async (name, opts) => {
-  try {
-    await themeBuild(name, { failOnContrast: opts.failOnContrast });
-  } catch (err) {
-    console.error(pc10.red("\u2716"), err.message);
-    process.exitCode = 1;
-  }
-});
-var preset = program.command("preset").description("Read a Kinetix Create preset code (KX1_\u2026) produced by kinetixui.com/create.");
-preset.command("decode").description("Show what a preset contains. Accepts a KX1_ code or a full /create?preset=\u2026 URL.").argument("<preset>", "a KX1_ code, or a share URL").option("--json", "print the configuration as JSON", false).action((input, opts) => {
-  try {
-    presetDecode(input, { json: opts.json });
-  } catch (err) {
-    console.error(pc10.red("\u2716"), err.message);
-    process.exitCode = 1;
-  }
-});
-preset.command("css").description("Resolve a preset into its web CSS override block \u2014 the same output the workspace exports for Web CSS. This command is CSS only; see `preset swiftui|compose|flutter`.").argument("<preset>", "a KX1_ code, or a share URL").option("-o, --output <file>", "write to a file instead of stdout").action(async (input, opts) => {
-  try {
-    await presetCss(input, { output: opts.output });
-  } catch (err) {
-    console.error(pc10.red("\u2716"), err.message);
-    process.exitCode = 1;
-  }
-});
-preset.command("swiftui").description("Resolve a preset into a SwiftUI theme file (KinetixColors, light and dark). Colours only \u2014 SwiftUI has no radius or elevation token to carry. No Compose or Flutter output.").argument("<preset>", "a KX1_ code, or a share URL").option("-o, --output <file>", "write to a file instead of stdout").option("-n, --name <symbol>", "the Swift enum to generate", DEFAULT_SWIFT_SYMBOL).action(async (input, opts) => {
-  try {
-    await presetSwiftUi(input, { output: opts.output, name: opts.name });
-  } catch (err) {
-    console.error(pc10.red("\u2716"), err.message);
-    process.exitCode = 1;
-  }
-});
-preset.command("compose").description("Resolve a preset into a Jetpack Compose theme file (KinetixColors, light and dark). Colours only \u2014 Compose has no runtime radius or elevation token to carry. No Flutter or Android XML output.").argument("<preset>", "a KX1_ code, or a share URL").option("-o, --output <file>", "write to a file instead of stdout").option("-n, --name <symbol>", "the Kotlin object to generate", DEFAULT_COMPOSE_SYMBOL).action(async (input, opts) => {
-  try {
-    await presetCompose(input, { output: opts.output, name: opts.name });
-  } catch (err) {
-    console.error(pc10.red("\u2716"), err.message);
-    process.exitCode = 1;
-  }
-});
-preset.command("flutter").description("Resolve a preset into a Flutter theme file (KinetixColors, light and dark). Colours only \u2014 Flutter's radius and elevation are not runtime-themeable. No Android XML output.").argument("<preset>", "a KX1_ code, or a share URL").option("-o, --output <file>", "write to a file instead of stdout").option("-n, --name <symbol>", "the Dart class to generate", DEFAULT_FLUTTER_SYMBOL).action(async (input, opts) => {
-  try {
-    await presetFlutter(input, { output: opts.output, name: opts.name });
-  } catch (err) {
-    console.error(pc10.red("\u2716"), err.message);
-    process.exitCode = 1;
-  }
-});
-preset.command("url").description("Print the canonical share URL for a preset. Prints it \u2014 piping it to your opener is up to you.").argument("<preset>", "a KX1_ code, or a share URL").option("-s, --site <origin>", "site origin", "https://kinetixui.com").action((input, opts) => {
-  try {
-    presetUrlCommand(input, { site: opts.site });
-  } catch (err) {
-    console.error(pc10.red("\u2716"), err.message);
-    process.exitCode = 1;
-  }
-});
-program.parseAsync();
+createProgram().parseAsync();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kinetixui/cli",
-  "version": "0.23.2",
+  "version": "0.24.0",
   "description": "Add KinetixUI components and tokens to your project.",
   "type": "module",
   "license": "MIT",
@@ -23,10 +23,12 @@
   "devDependencies": {
     "@kinetixui/create-preset": "0.0.0",
     "@kinetixui/create-theme": "0.0.0",
-    "@types/node": "^22.20.3",
+    "@types/node": "^22.20.4",
     "@types/prompts": "^2.4.9",
+    "jsdom": "^30.1.0",
     "tsup": "^8.5.1",
-    "typescript": "^5.9.3"
+    "typescript": "^5.9.3",
+    "vitest": "^5.0.2"
   },
   "engines": {
     "node": ">=18"
@@ -37,7 +39,9 @@
   },
   "scripts": {
     "build": "tsup src/index.ts --format esm --clean",
-    "typecheck": "tsc --noEmit",
-    "dev": "tsup src/index.ts --format esm --watch --onSuccess \"node dist/index.js\""
+    "dev": "tsup src/index.ts --format esm --watch --onSuccess \"node dist/index.js\"",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
   }
 }