@motion-proto/live-tokens 0.73.0 → 0.75.0

package/bin/create.mjs

@@ -78,7 +78,7 @@ export function runCreate({ targetDir, pkgRoot, force = false }) {
 export function formatCreateResult({ appName, targetDir }, targetArg) {
   return [
     ``,
-    `Scaffolded ${appName} → ${targetDir}`,
+    `Scaffolded ${appName} in ${targetDir}`,
     ``,
     `Next steps:`,
     `  cd ${targetArg}`,

package/bin/lib/catalogue.mjs

@@ -1,28 +1,33 @@
 // The registry as a query. Every component a project has, shipped or its own,
 // with the props each takes and the tokens each declares, and every theme token
-// grouped by family. Read from files through the same vocabulary the checkers
+// grouped by scale. Read from files through the same vocabulary the checkers
 // use, so a skill or a script sees exactly what the checkers will hold it to.
 
 import { readFileSync } from 'node:fs';
 import { relative } from 'node:path';
-import { CONTRACT_FAMILIES } from './tokenVocabulary.mjs';
+import { CONTRACT_SCALES } from './tokenVocabulary.mjs';
 
-/** The runtime file's leading HTML comment, which is where a component says what it is for. */
+/** The runtime file's leading HTML comment, which is where a component says what
+    it is for. A labelled line (`Use for:`, `Not for:`, `Emphasis:`) opens a line
+    of the description and every other line continues the one above it, so the
+    comment wraps in the source and still reads as its four lines here. */
 function descriptionOf(source) {
   const m = source.match(/^\s*<!--([\s\S]*?)-->/);
   if (!m) return '';
-  return m[1]
-    .split('\n')
-    .map((line) => line.trim())
-    .join(' ')
-    .replace(/\s+/g, ' ')
-    .trim()
-    .replace(/^\S+\.svelte\s*[—–-]+\s*/, '');
+  const lines = [];
+  for (const raw of m[1].split('\n')) {
+    const line = raw.trim().replace(/\s+/g, ' ');
+    if (!line) continue;
+    if (lines.length && !/^[A-Z][A-Za-z ]{0,20}:/.test(line)) lines[lines.length - 1] += ` ${line}`;
+    else lines.push(line);
+  }
+  if (lines.length) lines[0] = lines[0].replace(/^\S+\.svelte\s*(?:[—–-]+|\.)\s*/, '');
+  return lines.join('\n');
 }
 
-function familyOf(name) {
+function scaleOf(name) {
   const stem = name.replace(/^--/, '');
-  const hit = CONTRACT_FAMILIES
+  const hit = CONTRACT_SCALES
     .filter((f) => stem === f || stem.startsWith(`${f}-`))
     .sort((a, b) => b.length - a.length)[0];
   return hit ?? stem.split('-')[0];
@@ -62,15 +67,15 @@ export function describeTokens(vocab, { root = process.cwd() } = {}) {
       if (!values.has(m[1])) values.set(m[1], m[2].trim());
     }
   }
-  const byFamily = new Map();
+  const byScale = new Map();
   for (const name of vocab.themeTokens) {
-    const family = familyOf(name);
-    if (!byFamily.has(family)) byFamily.set(family, []);
-    byFamily.get(family).push({ name, value: values.get(name) ?? '' });
+    const scale = scaleOf(name);
+    if (!byScale.has(scale)) byScale.set(scale, []);
+    byScale.get(scale).push({ name, value: values.get(name) ?? '' });
   }
   return {
     tokensCss: vocab.tokensCssPath ? relative(root, vocab.tokensCssPath) : null,
-    families: [...byFamily].map(([family, tokens]) => ({ family, tokens })),
+    scales: [...byScale].map(([scale, tokens]) => ({ scale, tokens })),
     components: [...vocab.components.values()].map((c) => ({
       id: c.id,
       tokens: [...c.tokens].map(([name, value]) => ({ name, default: value })),
@@ -78,13 +83,15 @@ export function describeTokens(vocab, { root = process.cwd() } = {}) {
   };
 }
 
+const describeLines = (c) => (c.description ? c.description.split('\n') : []);
+
 export function formatComponents(list, { id } = {}) {
   const lines = [];
   if (id) {
     const c = list.find((x) => x.id === id);
     if (!c) return `No component "${id}". Run \`live-tokens components\` for the list.`;
-    lines.push(`${c.name} (${c.id}, ${c.origin}${c.registered ? '' : ', NOT registered'})  ${c.file}`);
-    if (c.description) lines.push(`  ${c.description}`);
+    lines.push(`${c.name} (${c.id}, ${c.origin}${c.registered ? '' : ', unregistered'})  ${c.file}`);
+    for (const line of describeLines(c)) lines.push(`  ${line}`);
     if (c.props.length) {
       lines.push('  props:');
       for (const p of c.props) lines.push(`    ${p.name}${p.values ? `: ${p.values.join(' | ')}` : p.type ? `: ${p.type}` : ''}`);
@@ -96,7 +103,7 @@ export function formatComponents(list, { id } = {}) {
   for (const c of list) {
     const variants = c.variants.length ? `  variants: ${c.variants.join(', ')}` : '';
     lines.push(`${c.id.padEnd(20)} ${c.origin.padEnd(8)} ${c.name}${c.registered ? '' : '  (NOT registered)'}${variants}`);
-    if (c.description) lines.push(`${''.padEnd(29)} ${c.description}`);
+    for (const line of describeLines(c)) lines.push(`    ${line}`);
   }
   lines.push('');
   const unregistered = list.filter((c) => !c.registered).length;
@@ -107,21 +114,21 @@ export function formatComponents(list, { id } = {}) {
   return lines.join('\n');
 }
 
-export function formatTokens(desc, { family } = {}) {
+export function formatTokens(desc, { scale } = {}) {
   const lines = [];
-  const families = family ? desc.families.filter((f) => f.family === family) : desc.families;
-  if (family && families.length === 0) {
-    return `No family "${family}". Families: ${desc.families.map((f) => f.family).join(', ')}.`;
+  const scales = scale ? desc.scales.filter((s) => s.scale === scale) : desc.scales;
+  if (scale && scales.length === 0) {
+    return `No token scale "${scale}". Scales: ${desc.scales.map((s) => s.scale).join(', ')}.`;
   }
-  lines.push(`Theme tokens from ${desc.tokensCss ?? '(no tokens.css found)'}`);
-  for (const f of families) {
+  lines.push(`Design tokens from ${desc.tokensCss ?? '(no tokens.css found)'}`);
+  for (const s of scales) {
     lines.push('');
-    lines.push(`${f.family} (${f.tokens.length})`);
-    for (const t of f.tokens) lines.push(`  ${t.name}: ${t.value}`);
+    lines.push(`${s.scale} (${s.tokens.length})`);
+    for (const t of s.tokens) lines.push(`  ${t.name}: ${t.value}`);
   }
-  if (!family) {
+  if (!scale) {
     lines.push('');
-    lines.push(`Component tokens: ${desc.components.reduce((n, c) => n + c.tokens.length, 0)} across ${desc.components.length} component(s). \`live-tokens components <id>\` lists one component's.`);
+    lines.push(`Semantic properties: ${desc.components.reduce((n, c) => n + c.tokens.length, 0)} across ${desc.components.length} component(s). \`live-tokens components <id>\` lists one component's.`);
   }
   return lines.join('\n');
 }

package/bin/lib/findings.mjs

@@ -52,38 +52,65 @@ export function isExcluded(relPath, root) {
  * Unrecognised flags are returned in `rest` for the caller to handle.
  */
 export function parseCheckFlags(argv) {
-  const opts = { off: [], warn: [], error: [], strict: false, json: false, rest: [] };
+  const opts = { off: [], warn: [], error: [], strict: false, json: false, tests: false, rest: [] };
   for (const arg of argv) {
     const m = arg.match(/^--(off|warn|error)=(.+)$/);
     if (m) {
       opts[m[1]].push(...m[2].split(',').map((s) => s.trim()).filter(Boolean));
     } else if (arg === '--strict') opts.strict = true;
     else if (arg === '--json') opts.json = true;
+    else if (arg === '--tests') opts.tests = true;
     else opts.rest.push(arg);
   }
   return opts;
 }
 
+/** The same last-wins resolution `applySeverity` applies per finding, exposed
+ *  standalone so coverage (which has no findings to attach a severity to, but
+ *  still has to honor `--off`) can ask the same question. */
+export function resolveRuleSeverity(ruleId, rules, opts = {}, config = {}) {
+  const configured = config.rules ?? {};
+  let severity = rules[ruleId] ?? 'error';
+  if (SEVERITIES.includes(configured[ruleId])) severity = configured[ruleId];
+  if (opts.off?.includes(ruleId)) severity = 'off';
+  if (opts.warn?.includes(ruleId)) severity = 'warn';
+  if (opts.error?.includes(ruleId)) severity = 'error';
+  if (opts.strict && severity === 'warn') severity = 'error';
+  return severity;
+}
+
 /**
  * Resolve each finding's severity and drop the ones turned off.
  * `rules` maps rule id to its default severity.
  */
-export function applySeverity(findings, rules, opts = {}, config = {}) {
-  const configured = config.rules ?? {};
-  const resolve = (id) => {
-    let severity = rules[id] ?? 'error';
-    if (SEVERITIES.includes(configured[id])) severity = configured[id];
-    if (opts.off?.includes(id)) severity = 'off';
-    if (opts.warn?.includes(id)) severity = 'warn';
-    if (opts.error?.includes(id)) severity = 'error';
-    if (opts.strict && severity === 'warn') severity = 'error';
-    return severity;
-  };
+export function applySeverity(findings, rules, opts = {}, config = {}, fixes = {}) {
   return findings
-    .map((f) => ({ ...f, severity: resolve(f.rule) }))
+    .map((f) => ({
+      ...f,
+      severity: resolveRuleSeverity(f.rule, rules, opts, config),
+      ...(fixes[f.rule] ? { fix: fixes[f.rule] } : {}),
+    }))
     .filter((f) => f.severity !== 'off');
 }
 
+/**
+ * A coverage entry for a rule resolved to severity 'off' becomes 'disabled',
+ * regardless of what actually happened: the plan requires `--off` to stay
+ * visible as disabled coverage rather than silently reading as a pass (an
+ * obligation that failed but was silenced is not the same as one that ran
+ * clean), and disabled coverage can never establish a complete pass.
+ */
+export function applyCoverageSeverity(coverage, rules, opts = {}, config = {}) {
+  const out = {};
+  for (const [id, ruleMap] of Object.entries(coverage)) {
+    out[id] = {};
+    for (const [rule, entry] of Object.entries(ruleMap)) {
+      out[id][rule] = resolveRuleSeverity(rule, rules, opts, config) === 'off' ? { status: 'disabled' } : entry;
+    }
+  }
+  return out;
+}
+
 export function countBySeverity(findings) {
   return {
     errors: findings.filter((f) => f.severity === 'error').length,
@@ -117,7 +144,11 @@ export function formatFindings(findings, { label, checked = 0 } = {}) {
   return lines.join('\n');
 }
 
-export function toJson(findings, { label, checked = 0 } = {}) {
+export function toJson(findings, { label, checked = 0, coverage } = {}) {
   const { errors, warnings } = countBySeverity(findings);
-  return JSON.stringify({ check: label, checked, errors, warnings, findings }, null, 2);
+  return JSON.stringify(
+    { check: label, checked, errors, warnings, findings, ...(coverage ? { coverage } : {}) },
+    null,
+    2,
+  );
 }

package/bin/lib/liveState.mjs

@@ -0,0 +1,110 @@
+// The live state the three `set-*` workers read, in one place.
+//
+// Every resolver mirrors the dev server's own resolution order — the unsaved
+// buffer, then the open theme's copy by value, then the shipped default — so a
+// CLI edits what the page runs. Pure file reads: the caller passes the resolved
+// dirs, so nothing here loads `dist-plugin` and `bin/engineLoadsLazily.test.ts`
+// holds by construction.
+
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const packageDataDir = resolve(dirname(fileURLToPath(import.meta.url)), '../..', 'src/live-tokens/data');
+
+function readJsonIfExists(path) {
+  if (!existsSync(path)) return null;
+  try {
+    return JSON.parse(readFileSync(path, 'utf8'));
+  } catch (err) {
+    throw new Error(`${path} is not valid JSON: ${err instanceof Error ? err.message : String(err)}`);
+  }
+}
+
+/** Local tree first, then the copy the installed package ships. */
+function readData(localDir, packageSubdir, fileName) {
+  return (
+    readJsonIfExists(join(localDir, `${fileName}.json`)) ??
+    readJsonIfExists(join(packageDataDir, packageSubdir, `${fileName}.json`))
+  );
+}
+
+/** `_fileName` and `_source` are read-door markers, never part of a document. */
+export function stripMarkers(value) {
+  if (!value || typeof value !== 'object') return value;
+  const { _fileName, _source, ...rest } = value;
+  return rest;
+}
+
+export function componentNames(componentConfigsDir) {
+  if (!existsSync(componentConfigsDir)) return [];
+  return readdirSync(componentConfigsDir, { withFileTypes: true })
+    .filter((e) => e.isDirectory())
+    .map((e) => e.name)
+    .sort();
+}
+
+export function readActiveTheme(themesDir) {
+  if (!themesDir) return null;
+  const slug = readJsonIfExists(join(themesDir, '_active.json'))?.activeFile ?? 'default';
+  const theme = readData(themesDir, 'themes', slug);
+  return theme ? { slug, theme } : null;
+}
+
+export function readLiveColorsAndType(colorsAndTypeDir, active) {
+  const working = readJsonIfExists(join(colorsAndTypeDir, '_working.json'));
+  if (working) return { colorsAndType: stripMarkers(working), source: 'working' };
+  if (active?.theme?.colorsAndType) {
+    return { colorsAndType: stripMarkers(active.theme.colorsAndType), source: 'theme' };
+  }
+  const shipped = readData(colorsAndTypeDir, 'colors-and-type', 'default');
+  if (!shipped) throw new Error(`no colors and type to read at ${colorsAndTypeDir}`);
+  return { colorsAndType: stripMarkers(shipped), source: 'default' };
+}
+
+/** `updatedAt` records when a buffer was written, not what it holds, so the
+ *  comparison that tells a discard from an edit ignores it. Both writers of
+ *  `colors-and-type/_working.json` ask this one question, and a rule that kept
+ *  `updatedAt` missed every buffer the other verb had stamped. */
+export function sameContent(a, b) {
+  const strip = ({ updatedAt: _updatedAt, ...rest }) => rest;
+  return JSON.stringify(strip(a)) === JSON.stringify(strip(b));
+}
+
+/** Which layer sits under the buffer: the open theme when it carries colors and
+ *  type, else the shipped default. A report that names the layer reads it from
+ *  here rather than re-deriving the fall-through, which is how the discard
+ *  message came to name a theme that was not open. */
+export const savedColorsAndTypeSource = (active) => (active?.theme?.colorsAndType ? 'theme' : 'default');
+
+/** The layer under the buffer. Returning the buffer to exactly this is a
+ *  discard, not an edit, so a caller compares against it before writing. */
+export function readSavedColorsAndType(colorsAndTypeDir, active) {
+  const saved =
+    savedColorsAndTypeSource(active) === 'theme'
+      ? active.theme.colorsAndType
+      : readData(colorsAndTypeDir, 'colors-and-type', 'default');
+  return saved ? stripMarkers(saved) : null;
+}
+
+/** Each component's live config, and whether a buffer or the open document
+ *  answered. Every theme carries every component by value, but this is a raw
+ *  file read, ahead of any server-side fill — a theme written before a
+ *  component existed can still omit it, so a missing entry falls back to the
+ *  shipped default the same way the theme's own fill would, and still reports
+ *  as the document. */
+export function readLiveComponentConfigs(componentConfigsDir, active) {
+  const configs = {};
+  const sources = {};
+  for (const comp of componentNames(componentConfigsDir)) {
+    const working = readJsonIfExists(join(componentConfigsDir, comp, '_working.json'));
+    const config =
+      working ??
+      active?.theme?.componentConfigs?.[comp] ??
+      readData(join(componentConfigsDir, comp), `component-configs/${comp}`, 'default');
+    if (!config) continue;
+    configs[comp] = stripMarkers(config);
+    sources[comp] = working ? 'working' : 'theme';
+  }
+  return { configs, sources };
+}

package/bin/lib/report.mjs

@@ -120,7 +120,7 @@ const list = (items, max = 20) =>
 
 export function formatReport(r) {
   const out = [];
-  out.push(`Project: ${r.project.pages} page file(s), ${r.project.components} component(s), ${r.project.themeTokens} theme tokens from ${r.project.tokensCss ?? '(no tokens.css)'}`);
+  out.push(`Project: ${r.project.pages} page file(s), ${r.project.components} component(s), ${r.project.themeTokens} design tokens from ${r.project.tokensCss ?? '(no tokens.css)'}`);
   if (r.migrations) {
     out.push('');
     out.push(`Migrations: ${r.migrations.status}${r.migrations.pending?.length ? ` (${list(r.migrations.pending)})` : ''}`);
@@ -131,11 +131,11 @@ export function formatReport(r) {
   const unread = r.components.filter((c) => c.unread.length);
   out.push(`  tokens declared and read by their own CSS: ${r.components.reduce((n, c) => n + c.tokens - c.unread.length, 0)} of ${r.components.reduce((n, c) => n + c.tokens, 0)}`);
   for (const c of unread) out.push(`    ${c.id}: ${c.unread.length} unread (${list(c.unread, 6)})`);
+  const undescribed = r.components.filter((c) => !c.described).map((c) => c.id);
+  if (undescribed.length) out.push(`  no description comment: ${list(undescribed)}`);
   const custom = r.components.filter((c) => c.origin === 'custom');
   out.push(`  custom: ${custom.length}${custom.length ? ` (${list(custom.map((c) => c.id))})` : ''}`);
   if (r.usage.customUnregistered.length) out.push(`    not registered: ${list(r.usage.customUnregistered)}`);
-  const undescribed = custom.filter((c) => !c.described).map((c) => c.id);
-  if (undescribed.length) out.push(`    no description comment: ${list(undescribed)}`);
 
   out.push('');
   out.push('Usage');

package/bin/lib/tokenVocabulary.mjs

@@ -25,18 +25,18 @@ const PKG_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '../..');
 
 const SHIPPED_COMPONENTS_DIR = 'src/system/components';
 
-/** Families whose names are governed by the token contract (see TOKENS.md). */
-export const CONTRACT_FAMILIES = [
+/** Token scales whose names are governed by the token contract (see TOKENS.md). */
+export const CONTRACT_SCALES = [
   'surface', 'text', 'border', 'color', 'space', 'radius', 'font', 'line-height',
   'letter-spacing', 'shadow', 'blur', 'icon-size', 'scrim', 'tint', 'columns',
   'heading', 'body', 'editorial', 'eyebrow', 'code', 'easing', 'duration', 'zoom',
   'gradient', 'stroke',
 ];
 
-/** True when `name` belongs to a contract-governed family, so a miss is a typo. */
+/** True when `name` belongs to a contract-governed scale, so a miss is a typo. */
 export function isContractToken(name) {
   const stem = name.replace(/^--/, '');
-  return CONTRACT_FAMILIES.some((f) => stem === f || stem.startsWith(`${f}-`));
+  return CONTRACT_SCALES.some((f) => stem === f || stem.startsWith(`${f}-`));
 }
 
 /** Every `--name:` declared anywhere in a stylesheet or style block. */

package/bin/migrate-routes.mjs

@@ -149,8 +149,8 @@ export function formatRouteResult(result, { check = false } = {}) {
   const { rewritten, pendingWrite, advisory } = result;
   if (!rewritten.length && !pendingWrite.length && !advisory.length) return '';
 
-  const ref = (h) => `      ${h.file}:${h.line}  ${h.kind} '${h.old}' → '${h.next}'`;
-  const lines = ['Route references — /editor, /components, /docs moved to /live-tokens/* in 0.35.0:'];
+  const ref = (h) => `      ${h.file}:${h.line}  ${h.kind} '${h.old}' to '${h.next}'`;
+  const lines = ['Route references: /editor, /components, /docs moved to /live-tokens/* in 0.35.0:'];
 
   if (rewritten.length) {
     lines.push(`  ✓ Rewrote ${rewritten.length} reference(s):`);
@@ -160,7 +160,7 @@ export function formatRouteResult(result, { check = false } = {}) {
     lines.push(
       check
         ? `  Would rewrite ${pendingWrite.length} reference(s) with --write:`
-        : `  ${pendingWrite.length} reference(s) can be rewritten — re-run with --write to apply:`,
+        : `  ${pendingWrite.length} reference(s) can be rewritten. Re-run with --write to apply:`,
     );
     pendingWrite.forEach((h) => lines.push(ref(h)));
   }
@@ -169,8 +169,8 @@ export function formatRouteResult(result, { check = false } = {}) {
     advisory.forEach((h) => {
       const why =
         h.reason === 'docs-never'
-          ? `/docs is never auto-rewritten — update to '${h.next}' only if it points at the package guide`
-          : `you declare or relocate '${h.old}' yourself — leave it if it's your route`;
+          ? `/docs is never auto-rewritten. Update to '${h.next}' only when it points at the package guide`
+          : `the project declares or relocates '${h.old}'. Leave it when it is the project's own route`;
       lines.push(`      ${h.file}:${h.line}  ${h.kind} '${h.old}'  (${why})`);
     });
   }

package/bin/migrate.mjs

@@ -127,13 +127,13 @@ export function formatMigrateDataResult(result) {
     // `sketch-presets/` → `sketch-styles/`. Told apart by the destination
     // name, since `LegacyRename` carries no reason of its own.
     const reason = basename(to) === 'sketch-styles' ? 'sketchstyle rename' : '0.48 layout';
-    lines.push(`  ${planned ? 'would move' : 'moved'} ${rel(from)} → ${rel(to)} (${reason})`);
+    lines.push(`  ${planned ? 'would move' : 'moved'} ${rel(from)} to ${rel(to)} (${reason})`);
   }
   for (const p of result.upgradedThemes) {
     lines.push(`  ${planned ? 'would carry' : 'carried'} ${rel(p)} by value (was a pre-v3 theme naming files)`);
   }
   if (result.production) {
-    lines.push(`  production theme → "${result.production.slug}" (${HOW_SAID[result.production.how]})`);
+    lines.push(`  production theme: "${result.production.slug}" (${HOW_SAID[result.production.how]})`);
   }
   if (result.recoveredThemePath) {
     lines.push(`  ${planned ? 'would write' : 'wrote'} ${rel(result.recoveredThemePath)}`);
@@ -148,13 +148,13 @@ export function formatMigrateDataResult(result) {
     lines.push(`  ${planned ? 'would delete' : 'deleted'} ${rel(p)}: a copy of a saved theme`);
   }
   for (const p of result.keptUserFiles) {
-    lines.push(`  kept ${rel(p)}: it matches no theme, so it is yours`);
+    lines.push(`  kept ${rel(p)}: it matches no theme, so it stays`);
   }
   for (const note of result.droppedRefs) {
     lines.push(`  ${note}`);
   }
   for (const p of result.notThemes) {
-    lines.push(`  left ${rel(p)} alone: it is a colors-and-type file, not a theme`);
+    lines.push(`  left ${rel(p)} alone: it is a colors-and-type file`);
   }
   for (const p of result.shadowedDefaults) {
     lines.push(`  kept ${rel(p)}: it shadows the default the package ships, which has moved on`);

package/bin/save-theme.mjs

@@ -0,0 +1,176 @@
+// `live-tokens save-theme` worker.
+//
+// Composes the live state into a theme document at `themes/<slug>.json` and
+// opens it. Live state, and only live state: each layer resolves the way the
+// dev server resolves it — the unsaved buffer, then the open theme's copy by
+// value, then the shipped default — so the theme this writes is the look the
+// page renders. Opening clears every `_working.json` and points
+// `themes/_active.json` at the new document, exactly as the editor's apply door
+// does; `--no-activate` writes the file and leaves the live state alone, which
+// is how a set of themes comes off one starting look.
+//
+// This is the only verb that writes a theme. The three `set-*` verbs write
+// buffers.
+
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import {
+  componentNames,
+  readActiveTheme,
+  readLiveColorsAndType,
+  readLiveComponentConfigs,
+} from './lib/liveState.mjs';
+
+const pkgRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+// The setColors bundle carries the slug helper, the component schema stamp and
+// the dir resolution; composing a theme needs no color pipeline of its own.
+const ENGINE = resolve(pkgRoot, 'dist-plugin/setColors/index.js');
+// Source of truth: src/editor/core/themes/themeTypes.ts, which
+// normalizeTheme.ts re-exports. This copy cannot import TS, so
+// `bin/schemaVersionCopies.test.ts` is what catches a drift.
+const THEME_SCHEMA_VERSION = 5;
+
+async function loadEngine() {
+  if (!existsSync(ENGINE)) {
+    throw new Error(
+      `setColors engine not found at ${relative(process.cwd(), ENGINE)}. ` +
+        `Build the plugin first (npm run build:plugin).`,
+    );
+  }
+  return import(ENGINE);
+}
+
+/** The destination file, read to keep its `createdAt`. Never the package copy:
+ *  this is the file about to be overwritten, not a layer to fall through to. */
+function readLocalJson(path) {
+  return existsSync(path) ? JSON.parse(readFileSync(path, 'utf8')) : null;
+}
+
+/** `engine` is a test seam; the CLI always runs the compiled bundle. */
+export async function runSaveTheme({
+  name,
+  activate = true,
+  dryRun = false,
+  colorsAndTypeDir,
+  componentConfigsDir,
+  themesDir,
+  engine,
+} = {}) {
+  const { sanitizeFileName, resolveDataDirs, CURRENT_COMPONENT_SCHEMA_VERSION } =
+    engine ?? (await loadEngine());
+
+  const themeName = typeof name === 'string' ? name.trim() : '';
+  if (!themeName) throw new Error('save-theme needs a theme name');
+  const slug = sanitizeFileName(themeName);
+  if (slug === 'default') {
+    throw new Error('"default" is the protected package theme; pick another name');
+  }
+
+  const resolved = colorsAndTypeDir && componentConfigsDir && themesDir ? null : resolveDataDirs();
+  const dirs = {
+    colorsAndTypeDir: colorsAndTypeDir ?? resolved.colorsAndTypeDir,
+    componentConfigsDir: componentConfigsDir ?? resolved.componentConfigsDir,
+    themesDir: themesDir ?? resolved.themesDir,
+  };
+
+  const active = readActiveTheme(dirs.themesDir);
+  const { colorsAndType, source } = readLiveColorsAndType(dirs.colorsAndTypeDir, active);
+  const { configs, sources } = readLiveComponentConfigs(dirs.componentConfigsDir, active);
+
+  const themePath = join(dirs.themesDir, `${slug}.json`);
+  const existing = readLocalJson(themePath);
+  const now = new Date().toISOString();
+  const sketchSettings = active?.theme?.sketchSettings;
+
+  const theme = {
+    name: themeName,
+    createdAt: existing?.createdAt ?? now,
+    updatedAt: now,
+    schemaVersion: THEME_SCHEMA_VERSION,
+    colorsAndType: { ...colorsAndType, name: themeName },
+    componentConfigs: configs,
+    componentSchemaVersion: CURRENT_COMPONENT_SCHEMA_VERSION,
+    ...(sketchSettings ? { sketchSettings } : {}),
+  };
+
+  if (!dryRun) {
+    mkdirSync(dirs.themesDir, { recursive: true });
+    writeFileSync(themePath, JSON.stringify(theme, null, 2) + '\n');
+    if (activate) applyTheme(slug, dirs);
+  }
+
+  // `working` is the one source label that proves a buffer answered: a
+  // component the open theme omits reports as `theme` after falling through to
+  // its shipped default, so the report says what came from a buffer and names
+  // the fall-through for the rest rather than claiming a layer per component.
+  const bufferedComponents = componentNames(dirs.componentConfigsDir).filter(
+    (comp) => sources[comp] === 'working',
+  );
+
+  return {
+    name: themeName,
+    slug,
+    themePath,
+    existed: existing !== null,
+    dryRun,
+    activated: activate && !dryRun,
+    previousActive: active?.slug ?? 'default',
+    openTheme: active?.slug ?? null,
+    buffered: { colorsAndType: source === 'working', components: bufferedComponents },
+    components: Object.keys(configs).length,
+    sketchSettings: Boolean(sketchSettings),
+  };
+}
+
+/** The apply door's write set, reproduced: clear every working delta and point
+ *  `themes/_active.json` at the open document. Production is untouched. */
+function applyTheme(slug, dirs) {
+  const colorsWorking = join(dirs.colorsAndTypeDir, '_working.json');
+  if (existsSync(colorsWorking)) rmSync(colorsWorking);
+
+  for (const comp of componentNames(dirs.componentConfigsDir)) {
+    const workingPath = join(dirs.componentConfigsDir, comp, '_working.json');
+    if (existsSync(workingPath)) rmSync(workingPath);
+  }
+
+  writeFileSync(join(dirs.themesDir, '_active.json'), JSON.stringify({ activeFile: slug }));
+}
+
+export function formatSaveThemeResult(result) {
+  const root = process.cwd();
+  const lines = [];
+  const wrote = result.dryRun ? 'Would write' : result.existed ? 'Updated' : 'Created';
+  lines.push(`${wrote} theme "${result.name}" at ${relative(root, result.themePath)}`);
+  lines.push(`It carries the colors and type and ${result.components} component config(s) by value.`);
+
+  const edited = [
+    ...(result.buffered.colorsAndType ? ['colors and type'] : []),
+    ...result.buffered.components,
+  ];
+  const open = result.openTheme ? `the open theme "${result.openTheme}"` : 'the shipped defaults';
+  const kept = result.dryRun ? 'Would save' : 'Saved';
+  if (edited.length > 0) {
+    lines.push(`${kept} the buffer: ${edited.join(', ')}.`);
+    lines.push(`Everything else came from ${open}, or the shipped defaults where it carries no entry.`);
+  } else {
+    lines.push(`No buffer. ${kept} a copy of ${open}.`);
+  }
+  if (result.sketchSettings) lines.push(`Sketch settings rode through from the open theme.`);
+
+  if (result.activated) {
+    lines.push(
+      `\nLoaded "${result.slug}" (previously open: "${result.previousActive}"). ` +
+        `Adopt in the editor ships it to tokens.generated.css.`,
+    );
+  } else if (result.dryRun) {
+    lines.push(`\nDry run: nothing written under ${relative(root, dirname(result.themePath))}.`);
+  } else {
+    lines.push(
+      `\nNot loaded (--no-activate). The buffer is still open, so the next ` +
+        `save-theme starts from the same theme.`,
+    );
+  }
+  return lines.join('\n');
+}