material-theme-builder 3.2.0 → 3.3.0

package/dist/cli.js

@@ -1,11 +1,18 @@
 #!/usr/bin/env node
 
 // src/cli.ts
-import * as fs from "fs";
-import * as path from "path";
-import { Command, Option } from "commander";
+import * as fs2 from "fs";
+import * as path2 from "path";
+import { Command as Command2 } from "commander";
 import { z } from "zod";
 
+// src/cli.options.ts
+import {
+  Command,
+  InvalidArgumentError,
+  Option
+} from "commander";
+
 // src/lib/builder.ts
 import {
   argbFromHex as argbFromHex2,
@@ -116,9 +123,9 @@ function buildFigmaVariables(ctx) {
     paletteHexMap[paletteName] = {};
     for (const tone of STANDARD_TONES) {
       const argb = palette.tone(tone);
-      const path2 = `ref/palette/${paletteName}/${tone}`;
+      const path3 = `ref/palette/${paletteName}/${tone}`;
       const hex = hexFromArgb2(argb).toUpperCase();
-      paletteHexMap[paletteName][hex] = path2;
+      paletteHexMap[paletteName][hex] = path3;
       const color = {
         r: redFromArgb(argb) / 255,
         g: greenFromArgb(argb) / 255,
@@ -126,7 +133,7 @@ function buildFigmaVariables(ctx) {
         a: 1
       };
       variables.push({
-        path: path2,
+        path: path3,
         scopes: ["ALL_SCOPES"],
         values: { Light: color, Dark: color }
       });
@@ -210,8 +217,8 @@ function buildFigmaTokens(ctx) {
       $extensions: toDtcgExtensions(v)
     };
   }
-  function parsePath(path2) {
-    const parts = path2.split("/");
+  function parsePath(path3) {
+    const parts = path3.split("/");
     if (parts[0] === "ref" && parts[1] === "palette" && parts[2] && parts[3]) {
       return {
         kind: "palette",
@@ -661,6 +668,39 @@ function toShadcnVars(mergedColors) {
   });
   return Object.fromEntries(entries);
 }
+function toShadcnAliasVars(prefix, fallbacks) {
+  const entries = SHADCN_MAPPING.map(([cssVar, m3Token]) => {
+    const bare = cssVar.slice(2);
+    const property = `--${prefix}-sys-color-${m3Token}`;
+    return [
+      bare,
+      fallbacks ? `var(${property}, ${fallbacks[bare]})` : `var(${property})`
+    ];
+  });
+  return Object.fromEntries(entries);
+}
+function buildShadcnAliases(ctx) {
+  const lines = Object.entries(toShadcnAliasVars(ctx.prefix)).map(
+    ([name, value]) => `--${name}: ${value};`
+  );
+  return `:root,
+.dark {
+  ${lines.join("\n  ")}
+}
+`;
+}
+function buildShadcnRegistryItem(ctx, { fallback = false } = {}) {
+  const concrete = fallback ? buildShadcn(ctx) : void 0;
+  const vars = (mode) => toShadcnAliasVars(ctx.prefix, concrete?.[mode]);
+  return {
+    $schema: "https://ui.shadcn.com/schema/registry-item.json",
+    name: "material-theme-builder",
+    type: "registry:theme",
+    title: "Material Theme Builder",
+    description: `Points shadcn's CSS variables at the M3 custom properties \`<Mtb>\` emits, so every shadcn component follows whichever theme is above it in the tree.${fallback ? " Falls back to this theme's own colors where no `<Mtb>` is mounted." : ""}`,
+    cssVars: { light: vars("light"), dark: vars("dark") }
+  };
+}
 function buildShadcn(ctx) {
   const { mergedColorsLight, mergedColorsDark } = ctx;
   return {
@@ -671,6 +711,64 @@ function buildShadcn(ctx) {
 
 // src/lib/builder.tailwind.ts
 import { kebabCase as kebabCase3 } from "lodash-es";
+
+// src/lib/tokens.ts
+var DEFAULT_PREFIX = "md";
+var tokenDescriptions = {
+  background: "Default background color for screens and large surfaces.",
+  error: "Color for error states, used on elements like error text and icons.",
+  errorContainer: "Fill color for error container elements like error banners.",
+  inverseOnSurface: "Color for text and icons on inverse surface backgrounds.",
+  inversePrimary: "Primary color used on inverse surface, e.g. buttons on snackbars.",
+  inverseSurface: "Background for elements that require reverse contrast, such as snackbars.",
+  onBackground: "Color for text and icons displayed on the background.",
+  onError: "Color for text and icons on error-colored elements.",
+  onErrorContainer: "Color for text and icons on error container elements.",
+  onPrimary: "Color for text and icons on primary-colored elements like filled buttons.",
+  onPrimaryContainer: "Color for text and icons on primary container elements like tonal buttons.",
+  onPrimaryFixed: "Color for text and icons on primary fixed elements, constant across themes.",
+  onPrimaryFixedVariant: "Lower-emphasis color for text and icons on primary fixed elements.",
+  onSecondary: "Color for text and icons on secondary-colored elements.",
+  onSecondaryContainer: "Color for text and icons on secondary container elements.",
+  onSecondaryFixed: "Color for text and icons on secondary fixed elements, constant across themes.",
+  onSecondaryFixedVariant: "Lower-emphasis color for text and icons on secondary fixed elements.",
+  onSurface: "High-emphasis color for text and icons on surface backgrounds.",
+  onSurfaceVariant: "Medium-emphasis color for text and icons on surface variant backgrounds.",
+  onTertiary: "Color for text and icons on tertiary-colored elements.",
+  onTertiaryContainer: "Color for text and icons on tertiary container elements.",
+  onTertiaryFixed: "Color for text and icons on tertiary fixed elements, constant across themes.",
+  onTertiaryFixedVariant: "Lower-emphasis color for text and icons on tertiary fixed elements.",
+  outline: "Subtle color for borders and dividers to create visual separation.",
+  outlineVariant: "Lower-emphasis border color used for decorative dividers.",
+  primary: "Main brand color, used for key components like filled buttons and active states.",
+  primaryContainer: "Fill color for large primary elements like cards and tonal buttons.",
+  primaryFixed: "Fixed primary color that stays the same in light and dark themes.",
+  primaryFixedDim: "Dimmed variant of the fixed primary color for lower emphasis.",
+  scrim: "Color overlay for modals and dialogs to obscure background content.",
+  secondary: "Accent color for less prominent elements like filter chips and selections.",
+  secondaryContainer: "Fill color for secondary container elements like tonal buttons and input fields.",
+  secondaryFixed: "Fixed secondary color that stays the same in light and dark themes.",
+  secondaryFixedDim: "Dimmed variant of the fixed secondary color for lower emphasis.",
+  shadow: "Color for elevation shadows applied to surfaces and components.",
+  surface: "Default surface color for cards, sheets, and dialogs.",
+  surfaceBright: "Brightest surface variant, used for elevated surfaces in dark themes.",
+  surfaceContainer: "Middle-emphasis container color for grouping related content.",
+  surfaceContainerHigh: "Higher-emphasis container color for elements like cards.",
+  surfaceContainerHighest: "Highest-emphasis container color for text fields and other input areas.",
+  surfaceContainerLow: "Lower-emphasis container color for subtle surface groupings.",
+  surfaceContainerLowest: "Lowest-emphasis container, typically the lightest surface in light theme.",
+  surfaceDim: "Dimmest surface variant, used for recessed areas or dark theme backgrounds.",
+  surfaceTint: "Tint color applied to surfaces for subtle primary color elevation overlay.",
+  surfaceVariant: "Alternative surface color for differentiated areas like sidebar backgrounds.",
+  tertiary: "Third accent color for complementary elements that balance primary and secondary.",
+  tertiaryContainer: "Fill color for tertiary container elements like complementary cards.",
+  tertiaryFixed: "Fixed tertiary color that stays the same in light and dark themes.",
+  tertiaryFixedDim: "Dimmed variant of the fixed tertiary color for lower emphasis."
+};
+function isTokenName(key) {
+  return key in tokenDescriptions;
+}
+var tokenNames = Object.keys(tokenDescriptions).filter(isTokenName);
 var SHADE_TO_TONE = [
   [50, 95],
   [100, 90],
@@ -692,6 +790,8 @@ var CORE_PALETTES = [
   "neutral",
   "neutral-variant"
 ];
+
+// src/lib/builder.tailwind.ts
 function buildTailwind(ctx, options) {
   const { prefix, mergedColorsLight, hexCustomColors } = ctx;
   const lines = [];
@@ -724,17 +824,8 @@ function buildTailwind(ctx, options) {
   ${lines.join("\n  ")}
 }
 `;
-  if (options?.shadcn) {
-    const shadcnLines = SHADCN_MAPPING.map(
-      ([shadcnVar, m3Token]) => `${shadcnVar}: var(--${prefix}-sys-color-${m3Token});`
-    );
-    output += `
-:root,
-.dark {
-  ${shadcnLines.join("\n  ")}
-}
-`;
-  }
+  if (options?.shadcn) output += `
+${buildShadcnAliases(ctx)}`;
   return output;
 }
 
@@ -761,7 +852,24 @@ var DEFAULT_SCHEME = "tonalSpot";
 var DEFAULT_CONTRAST = 0;
 var DEFAULT_CUSTOM_COLORS = [];
 var DEFAULT_BLEND = true;
-var DEFAULT_PREFIX = "md";
+var HEX_COLOR = /^#?(?:[0-9a-f]{3}|[0-9a-f]{6}|[0-9a-f]{8})$/i;
+function isHexColor(value) {
+  return HEX_COLOR.test(value);
+}
+function assertHexColor(label, value) {
+  if (!isHexColor(value))
+    throw new Error(
+      `Invalid ${label}: '${value}'. Expected a hex color \u2014 3, 6 or 8 hex digits, with or without '#' (e.g. #6750A4).`
+    );
+}
+function assertHexInputs(source, cores, customColors) {
+  assertHexColor("source", source);
+  for (const [name, hex] of Object.entries(cores))
+    if (hex !== void 0) assertHexColor(name, hex);
+  customColors.forEach(
+    (color, i) => assertHexColor(`customColors[${i}].hex`, color.hex)
+  );
+}
 var STANDARD_TONES = [
   0,
   4,
@@ -812,61 +920,6 @@ var schemeToVariant = {
   fidelity: Variant.FIDELITY,
   content: Variant.CONTENT
 };
-var tokenDescriptions = {
-  background: "Default background color for screens and large surfaces.",
-  error: "Color for error states, used on elements like error text and icons.",
-  errorContainer: "Fill color for error container elements like error banners.",
-  inverseOnSurface: "Color for text and icons on inverse surface backgrounds.",
-  inversePrimary: "Primary color used on inverse surface, e.g. buttons on snackbars.",
-  inverseSurface: "Background for elements that require reverse contrast, such as snackbars.",
-  onBackground: "Color for text and icons displayed on the background.",
-  onError: "Color for text and icons on error-colored elements.",
-  onErrorContainer: "Color for text and icons on error container elements.",
-  onPrimary: "Color for text and icons on primary-colored elements like filled buttons.",
-  onPrimaryContainer: "Color for text and icons on primary container elements like tonal buttons.",
-  onPrimaryFixed: "Color for text and icons on primary fixed elements, constant across themes.",
-  onPrimaryFixedVariant: "Lower-emphasis color for text and icons on primary fixed elements.",
-  onSecondary: "Color for text and icons on secondary-colored elements.",
-  onSecondaryContainer: "Color for text and icons on secondary container elements.",
-  onSecondaryFixed: "Color for text and icons on secondary fixed elements, constant across themes.",
-  onSecondaryFixedVariant: "Lower-emphasis color for text and icons on secondary fixed elements.",
-  onSurface: "High-emphasis color for text and icons on surface backgrounds.",
-  onSurfaceVariant: "Medium-emphasis color for text and icons on surface variant backgrounds.",
-  onTertiary: "Color for text and icons on tertiary-colored elements.",
-  onTertiaryContainer: "Color for text and icons on tertiary container elements.",
-  onTertiaryFixed: "Color for text and icons on tertiary fixed elements, constant across themes.",
-  onTertiaryFixedVariant: "Lower-emphasis color for text and icons on tertiary fixed elements.",
-  outline: "Subtle color for borders and dividers to create visual separation.",
-  outlineVariant: "Lower-emphasis border color used for decorative dividers.",
-  primary: "Main brand color, used for key components like filled buttons and active states.",
-  primaryContainer: "Fill color for large primary elements like cards and tonal buttons.",
-  primaryFixed: "Fixed primary color that stays the same in light and dark themes.",
-  primaryFixedDim: "Dimmed variant of the fixed primary color for lower emphasis.",
-  scrim: "Color overlay for modals and dialogs to obscure background content.",
-  secondary: "Accent color for less prominent elements like filter chips and selections.",
-  secondaryContainer: "Fill color for secondary container elements like tonal buttons and input fields.",
-  secondaryFixed: "Fixed secondary color that stays the same in light and dark themes.",
-  secondaryFixedDim: "Dimmed variant of the fixed secondary color for lower emphasis.",
-  shadow: "Color for elevation shadows applied to surfaces and components.",
-  surface: "Default surface color for cards, sheets, and dialogs.",
-  surfaceBright: "Brightest surface variant, used for elevated surfaces in dark themes.",
-  surfaceContainer: "Middle-emphasis container color for grouping related content.",
-  surfaceContainerHigh: "Higher-emphasis container color for elements like cards.",
-  surfaceContainerHighest: "Highest-emphasis container color for text fields and other input areas.",
-  surfaceContainerLow: "Lower-emphasis container color for subtle surface groupings.",
-  surfaceContainerLowest: "Lowest-emphasis container, typically the lightest surface in light theme.",
-  surfaceDim: "Dimmest surface variant, used for recessed areas or dark theme backgrounds.",
-  surfaceTint: "Tint color applied to surfaces for subtle primary color elevation overlay.",
-  surfaceVariant: "Alternative surface color for differentiated areas like sidebar backgrounds.",
-  tertiary: "Third accent color for complementary elements that balance primary and secondary.",
-  tertiaryContainer: "Fill color for tertiary container elements like complementary cards.",
-  tertiaryFixed: "Fixed tertiary color that stays the same in light and dark themes.",
-  tertiaryFixedDim: "Dimmed variant of the fixed tertiary color for lower emphasis."
-};
-function isTokenName(key) {
-  return key in tokenDescriptions;
-}
-var tokenNames = Object.keys(tokenDescriptions).filter(isTokenName);
 function deriveCustomPaletteName(tokenName, allPaletteNamesKebab) {
   let baseName = tokenName;
   if (/^on[A-Z]/.test(baseName) && baseName.length > 2) {
@@ -985,6 +1038,11 @@ function builder(hexSource, {
   customColors: hexCustomColors = DEFAULT_CUSTOM_COLORS,
   prefix = DEFAULT_PREFIX
 } = {}) {
+  assertHexInputs(
+    hexSource,
+    { primary, secondary, tertiary, error, neutral, neutralVariant },
+    hexCustomColors
+  );
   const sourceArgb = argbFromHex2(hexSource);
   const sourceHct = Hct2.fromInt(sourceArgb);
   const effectiveSource = primary || hexSource;
@@ -1128,6 +1186,8 @@ function builder(hexSource, {
     toFigmaTokens: () => buildFigmaTokens(ctx),
     toTailwind: (options) => buildTailwind(ctx, options),
     toShadcn: () => buildShadcn(ctx),
+    toShadcnAliases: () => buildShadcnAliases(ctx),
+    toShadcnRegistryItem: (options) => buildShadcnRegistryItem(ctx, options),
     toFlutter: () => buildFlutter(ctx),
     mergedColorsLight,
     mergedColorsDark,
@@ -1135,19 +1195,342 @@ function builder(hexSource, {
   };
 }
 
+// src/cli.options.ts
+function parseHexColor(value) {
+  if (!isHexColor(value))
+    throw new InvalidArgumentError(
+      "Expected a hex color \u2014 3, 6 or 8 hex digits, with or without '#' (e.g. #6750A4)."
+    );
+  return value;
+}
+function addSourceArgument(command) {
+  return command.argument(
+    "<source>",
+    "Source color in hex format (e.g. #6750A4)",
+    parseHexColor
+  );
+}
+function addThemeOptions(command) {
+  return command.addOption(
+    new Option("--scheme <name>", "Color scheme variant").choices(schemeNames).default(DEFAULT_SCHEME)
+  ).option(
+    "--contrast <number>",
+    "Contrast level from -1.0 to 1.0",
+    parseFloat,
+    DEFAULT_CONTRAST
+  ).option("--primary <hex>", "Primary color override", parseHexColor).option("--secondary <hex>", "Secondary color override", parseHexColor).option("--tertiary <hex>", "Tertiary color override", parseHexColor).option("--error <hex>", "Error color override", parseHexColor).option("--neutral <hex>", "Neutral color override", parseHexColor).option(
+    "--neutral-variant <hex>",
+    "Neutral variant color override",
+    parseHexColor
+  ).option(
+    "--no-fallback",
+    "Omit this theme's colors as the var() fallbacks in the registry item, so it renders nothing without an <Mtb> above it"
+  ).option(
+    "--prefix <string>",
+    "CSS variable prefix (e.g. md \u2192 --md-sys-color-*, --md-ref-palette-*)",
+    DEFAULT_PREFIX
+  );
+}
+var THEME_OPTIONS = addThemeOptions(new Command()).options;
+function builderOptions(opts) {
+  return {
+    scheme: opts.scheme,
+    contrast: opts.contrast,
+    primary: opts.primary,
+    secondary: opts.secondary,
+    tertiary: opts.tertiary,
+    error: opts.error,
+    neutral: opts.neutral,
+    neutralVariant: opts.neutralVariant,
+    prefix: opts.prefix
+  };
+}
+function specifiedThemeArgs(command) {
+  const args = [];
+  for (const option of THEME_OPTIONS) {
+    const name = option.attributeName();
+    if (command.getOptionValueSource(name) !== "cli") continue;
+    if (option.long) args.push(option.long);
+    if (!option.negate) args.push(String(command.opts()[name]));
+  }
+  return args;
+}
+function themeFrom(command) {
+  const opts = command.opts();
+  return {
+    options: builderOptions(opts),
+    // Declared as a negation, so commander's own default here is `true` -- the
+    // opposite of the API's, and deliberately so: a CLI knows the source color,
+    // which is what makes baking its colors in as the fallbacks free. See
+    // `buildShadcnRegistryItem()`.
+    fallback: opts.fallback ?? true,
+    args: specifiedThemeArgs(command)
+  };
+}
+
+// src/cli.shadcn.ts
+import { spawnSync } from "child_process";
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+import { InvalidArgumentError as InvalidArgumentError2 } from "commander";
+var NPX = ["npx", "--yes"];
+var DEFAULT_SHADCN = "shadcn@latest";
+var SELF = "material-theme-builder";
+var INIT_TARGET = "shadcn init";
+var ADD_TARGET = "shadcn add";
+var ITEM = "mtb.json";
+var APP_NAME = "material-theme-app";
+var NAME = { long: "--name", short: "-n", value: APP_NAME };
+var YES = { long: "--yes", short: "-y" };
+var INIT_DEFAULTS = [
+  { long: "--preset", short: "-p", value: "b0" },
+  { long: "--template", short: "-t", value: "vite" },
+  NAME,
+  YES
+];
+var ADD_DEFAULTS = [YES];
+function parseShadcnSpec(value) {
+  if (value.startsWith("-"))
+    throw new InvalidArgumentError2(
+      "A package spec cannot start with '-': npx would read it as one of its own options."
+    );
+  if (/^\d/.test(value))
+    throw new InvalidArgumentError2(
+      `That is a version, not a package spec -- write 'shadcn@${value}'.`
+    );
+  return value;
+}
+function addChainOptions(command) {
+  return command.option(
+    "--shadcn-cli <spec>",
+    "npx package spec for the shadcn CLI to run (a version, tag, fork or tarball \u2014 anything npx resolves)",
+    parseShadcnSpec,
+    DEFAULT_SHADCN
+  ).option(
+    "--print",
+    "Print the equivalent shell chain instead of running it"
+  );
+}
+function mentions(args, { long, short }) {
+  return args.some(
+    (arg) => arg === long || arg.startsWith(`${long}=`) || arg.startsWith(short)
+  );
+}
+function mergeDefaults(defaults, forwarded) {
+  const injected = defaults.filter((option) => !mentions(forwarded, option)).flatMap(
+    ({ long, value }) => value === void 0 ? [long] : [long, value]
+  );
+  return [...injected, ...forwarded];
+}
+function lastName(args) {
+  for (let i = args.length - 1; i >= 0; i--) {
+    const arg = args[i] ?? "";
+    if (arg === NAME.long || arg === NAME.short) return args[i + 1];
+    if (arg.startsWith(`${NAME.long}=`)) return arg.slice(NAME.long.length + 1);
+    if (arg.length > NAME.short.length && arg.startsWith(NAME.short))
+      return arg.slice(NAME.short.length);
+  }
+  return void 0;
+}
+function ownOptionIn(declared, forwarded) {
+  return forwarded.find(
+    (arg) => declared.some(
+      (option) => arg === option.long || arg === option.short || option.long !== void 0 && arg.startsWith(`${option.long}=`)
+    )
+  );
+}
+function refuseOwnOptions(command, forwarded, target) {
+  const misplaced = ownOptionIn(command.options, forwarded);
+  if (misplaced !== void 0)
+    fail(
+      `${misplaced} is ours, not shadcn's, so it belongs before the \`--\`. Everything after the separator is handed to \`${target}\` untouched.`
+    );
+}
+var DEFAULT_THEME = { options: {}, fallback: true, args: [] };
+function chainOptionsFrom(command) {
+  return { theme: themeFrom(command), shadcn: command.opts().shadcnCli };
+}
+function initPlan(source, forwarded = [], {
+  theme = DEFAULT_THEME,
+  shadcn = DEFAULT_SHADCN
+} = {}) {
+  const args = mergeDefaults(INIT_DEFAULTS, forwarded);
+  const dir = lastName(args) ?? APP_NAME;
+  return {
+    source,
+    theme,
+    dir,
+    steps: [
+      {
+        kind: "spawn",
+        label: INIT_TARGET,
+        argv: [...NPX, shadcn, "init", ...args],
+        where: "cwd"
+      },
+      { kind: "cd", dir },
+      { kind: "item", file: ITEM },
+      // The same spec as the step above, deliberately: a chain pinned for the
+      // scaffold and floating for the install is worse than one that floats
+      // throughout, since the two would disagree about the registry format
+      // without saying so.
+      {
+        kind: "spawn",
+        label: ADD_TARGET,
+        argv: [
+          ...NPX,
+          shadcn,
+          "add",
+          `./${ITEM}`,
+          ...mergeDefaults(ADD_DEFAULTS, [])
+        ],
+        where: "project"
+      },
+      { kind: "rm", file: ITEM },
+      // The handover: long-running by design, stdio inherited, ctrl-C reaching
+      // it. Package-manager detection is out of scope -- `shadcn init` under
+      // `npx` writes a `package-lock.json` and the `dev` script npm will run.
+      {
+        kind: "spawn",
+        label: "npm run dev",
+        argv: ["npm", "run", "dev"],
+        where: "project"
+      }
+    ]
+  };
+}
+function applyPlan(source, forwarded = [], {
+  theme = DEFAULT_THEME,
+  shadcn = DEFAULT_SHADCN
+} = {}) {
+  return {
+    source,
+    theme,
+    steps: [
+      { kind: "item", file: ITEM },
+      {
+        kind: "spawn",
+        label: ADD_TARGET,
+        argv: [
+          ...NPX,
+          shadcn,
+          "add",
+          `./${ITEM}`,
+          ...mergeDefaults(ADD_DEFAULTS, forwarded)
+        ],
+        where: "cwd"
+      },
+      { kind: "rm", file: ITEM }
+    ]
+  };
+}
+var SHELL_SAFE = /^[\w@%+=:,./-]+$/;
+function quote(argv) {
+  return argv.map(
+    (arg) => SHELL_SAFE.test(arg) ? arg : `'${arg.replaceAll("'", `'\\''`)}'`
+  ).join(" ");
+}
+function renderStep(plan, step) {
+  switch (step.kind) {
+    case "spawn":
+      return quote(step.argv);
+    case "cd":
+      return `cd ${step.dir}`;
+    // Rendered as the command someone could have run themselves -- theme options
+    // included, or the line would describe a different theme from the one the
+    // runner generates. The runner does the same thing in-process, being the very
+    // binary this spawns.
+    case "item":
+      return `${quote([...NPX, SELF, plan.source, ...plan.theme.args, "--format", "registry-item"])} > ${step.file}`;
+    case "rm":
+      return `rm ${step.file}`;
+  }
+}
+function renderChain(plan) {
+  return plan.steps.map((step) => renderStep(plan, step)).join(" && ");
+}
+function fail(message, code = 1) {
+  console.error(`Error: ${message}`);
+  process.exit(code);
+}
+function run({ label, argv }, cwd) {
+  const [command = "", ...args] = argv;
+  const { error, status, signal } = spawnSync(command, args, {
+    cwd,
+    stdio: "inherit",
+    shell: false
+  });
+  if (error) fail(`${label} could not be started: ${error.message}`);
+  if (signal) process.exit(128 + (os.constants.signals[signal] ?? 0));
+  if (status !== 0) fail(`${label} failed`, status ?? 1);
+}
+function writeItem({ source, theme }, file) {
+  if (fs.existsSync(file))
+    fail(
+      `${path.basename(file)} already exists and would be overwritten, then deleted. Move it aside first.`
+    );
+  process.on("exit", () => fs.rmSync(file, { force: true }));
+  const item = builder(source, theme.options).toShadcnRegistryItem({
+    fallback: theme.fallback
+  });
+  fs.writeFileSync(file, `${JSON.stringify(item, null, 2)}
+`);
+}
+function runStep(plan, step, projectDir) {
+  switch (step.kind) {
+    case "spawn":
+      return run(step, step.where === "project" ? projectDir : process.cwd());
+    case "item":
+      return writeItem(plan, path.join(projectDir, step.file));
+    case "rm":
+      return fs.rmSync(path.join(projectDir, step.file), { force: true });
+    // Nothing to do: the runner resolved the directory up front, where a shell
+    // would have changed into it. The step exists so that `--print` can say so.
+    case "cd":
+      return;
+  }
+}
+function runChain(plan) {
+  const projectDir = plan.dir ? path.resolve(plan.dir) : process.cwd();
+  if (plan.dir && fs.existsSync(projectDir))
+    fail(
+      `./${plan.dir} already exists. Pick another name with \`-- -n other-name\`, or remove it first.`
+    );
+  for (const step of plan.steps) runStep(plan, step, projectDir);
+}
+function execute(plan, command) {
+  if (command.opts().print === true) {
+    process.stdout.write(`${renderChain(plan)}
+`);
+    return;
+  }
+  runChain(plan);
+}
+function runInit(source, forwarded, command) {
+  refuseOwnOptions(command, forwarded, INIT_TARGET);
+  execute(initPlan(source, forwarded, chainOptionsFrom(command)), command);
+}
+function runApply(source, forwarded, command) {
+  refuseOwnOptions(command, forwarded, ADD_TARGET);
+  execute(applyPlan(source, forwarded, chainOptionsFrom(command)), command);
+}
+
 // src/cli.ts
 var customColorSchema = z.array(
   z.object({
     name: z.string(),
-    hex: z.string(),
+    hex: z.string().refine(
+      isHexColor,
+      "must be a hex color \u2014 3, 6 or 8 hex digits, with or without '#' (e.g. #FF5733)"
+    ),
     blend: z.boolean().default(DEFAULT_BLEND)
   })
 );
 function writeFigmaTokens(theme, outputDir) {
-  fs.mkdirSync(outputDir, { recursive: true });
+  fs2.mkdirSync(outputDir, { recursive: true });
   for (const [filename, content] of Object.entries(theme.toFigmaTokens())) {
-    const filePath = path.join(outputDir, filename);
-    fs.writeFileSync(filePath, JSON.stringify(content, null, 2) + "\n");
+    const filePath = path2.join(outputDir, filename);
+    fs2.writeFileSync(filePath, JSON.stringify(content, null, 2) + "\n");
     console.error(`wrote ${filePath}`);
   }
 }
@@ -1160,6 +1543,10 @@ function writeOutput(theme, opts) {
       return process.stdout.write(theme.toTailwind({ shadcn: opts.shadcn }));
     case "shadcn":
       return process.stdout.write(json(theme.toShadcn()));
+    case "registry-item":
+      return process.stdout.write(
+        json(theme.toShadcnRegistryItem({ fallback: opts.fallback }))
+      );
     case "flutter":
       return process.stdout.write(theme.toFlutter());
     case "figma":
@@ -1168,56 +1555,84 @@ function writeOutput(theme, opts) {
       return process.stdout.write(json(theme.toJson()));
   }
 }
-var program = new Command();
-program.name("material-theme-builder").description("Generate a color theme from a source color").argument("<source>", "Source color in hex format (e.g. #6750A4)").addOption(
-  new Option("--scheme <name>", "Color scheme variant").choices(schemeNames).default(DEFAULT_SCHEME)
+var program = new Command2();
+addThemeOptions(
+  addSourceArgument(
+    program.name("material-theme-builder").description("Generate a color theme from a source color")
+  ).enablePositionalOptions()
 ).option(
-  "--contrast <number>",
-  "Contrast level from -1.0 to 1.0",
-  parseFloat,
-  DEFAULT_CONTRAST
-).option("--primary <hex>", "Primary color override").option("--secondary <hex>", "Secondary color override").option("--tertiary <hex>", "Tertiary color override").option("--error <hex>", "Error color override").option("--neutral <hex>", "Neutral color override").option("--neutral-variant <hex>", "Neutral variant color override").option(
   "--custom-colors <json>",
   `Custom colors as JSON array (e.g. '[{"name":"brand","hex":"#FF5733","blend":true}]')`
 ).option(
   "--format <type>",
-  "Output format: json, css, figma, tailwind, shadcn, or flutter",
+  "Output format: json, css, figma, tailwind, shadcn, registry-item, or flutter",
   "figma"
 ).option("--output <dir>", "Output directory (required for figma format)").option(
   "--shadcn",
   "Append the shadcn var() alias block to --format tailwind (for concrete values, use --format shadcn)"
-).option(
-  "--prefix <string>",
-  "CSS variable prefix (e.g. md \u2192 --md-sys-color-*, --md-ref-palette-*)",
-  DEFAULT_PREFIX
-).action((source, opts) => {
+).action((source, opts, command) => {
   if (opts.shadcn && opts.format !== "tailwind") {
     console.error(
       "Error: --shadcn only applies to --format tailwind. For concrete color values, use --format shadcn."
     );
     process.exit(1);
   }
+  if (command.getOptionValueSource("fallback") === "cli" && opts.format !== "registry-item") {
+    console.error(
+      "Error: --no-fallback only applies to --format registry-item."
+    );
+    process.exit(1);
+  }
   let customColors = [];
   if (opts.customColors) {
-    const result2 = customColorSchema.safeParse(JSON.parse(opts.customColors));
-    if (!result2.success) {
+    let parsed;
+    try {
+      parsed = JSON.parse(opts.customColors);
+    } catch {
       console.error("Error: --custom-colors must be valid JSON");
       process.exit(1);
     }
+    const result2 = customColorSchema.safeParse(parsed);
+    if (!result2.success) {
+      const issue = result2.error.issues[0];
+      const where = issue?.path.length ? ` at ${issue.path.join(".")}` : "";
+      console.error(
+        `Error: --custom-colors${where}: ${issue?.message ?? "is invalid"}`
+      );
+      process.exit(1);
+    }
     customColors = result2.data;
   }
   const result = builder(source, {
-    scheme: opts.scheme,
-    contrast: opts.contrast,
-    primary: opts.primary,
-    secondary: opts.secondary,
-    tertiary: opts.tertiary,
-    error: opts.error,
-    neutral: opts.neutral,
-    neutralVariant: opts.neutralVariant,
-    customColors,
-    prefix: opts.prefix
+    ...builderOptions(opts),
+    customColors
   });
   writeOutput(result, opts);
 });
+addChainOptions(
+  addThemeOptions(
+    addSourceArgument(
+      program.command("shadcn-init").description(
+        "Scaffold a new shadcn app themed from a source color, and start it"
+      )
+    ).argument(
+      "[shadcn-args...]",
+      "Options after a `--`, forwarded verbatim to `shadcn init`"
+    )
+  )
+).action(
+  (source, shadcnArgs, _opts, command) => runInit(source, shadcnArgs, command)
+);
+addChainOptions(
+  addThemeOptions(
+    addSourceArgument(
+      program.command("shadcn-apply").description("Theme the shadcn project in the current directory")
+    ).argument(
+      "[shadcn-args...]",
+      "Options after a `--`, forwarded verbatim to `shadcn add`"
+    )
+  )
+).action(
+  (source, shadcnArgs, _opts, command) => runApply(source, shadcnArgs, command)
+);
 program.parse();