@motion-proto/live-tokens 0.73.0 → 0.74.0

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/save-theme.mjs

@@ -0,0 +1,177 @@
+// `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}" → ${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 package defaults';
+  const kept = result.dryRun ? 'Would save' : 'Saved';
+  if (edited.length > 0) {
+    lines.push(`${kept} your unsaved edits: ${edited.join(', ')}.`);
+    lines.push(`Everything else came from ${open}, or the shipped defaults where it carries no entry.`);
+  } else {
+    lines.push(`No unsaved edits; ${kept.toLowerCase()} a copy of ${open}.`);
+  }
+  if (result.sketchSettings) lines.push(`Sketch settings rode through from the open theme.`);
+
+  if (result.activated) {
+    lines.push(
+      `\nOpened "${result.slug}" (previously open: "${result.previousActive}"). ` +
+        `Reload the app to see it; switch back any time from Load in the editor's Theme panel. ` +
+        `Adopt it there to publish 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 opened (--no-activate). Your unsaved edits are still open, so the next ` +
+        `save-theme starts from the same look. Load "${result.slug}" from the editor's Theme panel to see it.`,
+    );
+  }
+  return lines.join('\n');
+}

package/bin/set-colors.mjs

@@ -0,0 +1,191 @@
+// `live-tokens set-colors` worker.
+//
+// Reads a base color file (JSON), builds the theme's whole color state via the
+// compiled engine (dist-plugin/setColors — the CLI never imports TS sources),
+// enforces the AA contrast gate, and writes the result into
+// `colors-and-type/_working.json`: the same buffer the editor's own palette
+// edits land in, so a recolor is an unsaved edit the user keeps by saving the
+// open theme or by running `save-theme`. Named colors-and-type files, themes,
+// tokens.css and fonts.css are never touched, and nothing is activated.
+//
+// Non-color content carries forward from the live colors and type, so a recolor
+// replaces the color identity and nothing else. Swatch gradients ride along
+// when user-tuned; stock ones are rebuilt from the new families by the engine.
+
+import { existsSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import {
+  readActiveTheme,
+  readLiveColorsAndType,
+  readSavedColorsAndType,
+  sameContent,
+  savedColorsAndTypeSource,
+} from './lib/liveState.mjs';
+
+const pkgRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const ENGINE = resolve(pkgRoot, 'dist-plugin/setColors/index.js');
+
+const SOURCE_LABELS = {
+  working: 'your unsaved edits',
+  theme: 'the open theme',
+  default: 'the package default',
+};
+
+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);
+}
+
+function readJson(path) {
+  return JSON.parse(readFileSync(path, 'utf8'));
+}
+
+/** `engine` is a test seam; the CLI always runs the compiled bundle. */
+export async function runSetColors({
+  baseColorsPath,
+  dryRun = false,
+  root = process.cwd(),
+  colorsAndTypeDir,
+  themesDir,
+  engine,
+} = {}) {
+  const { buildColors, resolveDataDirs } = engine ?? (await loadEngine());
+
+  const fullPath = resolve(root, baseColorsPath);
+  if (!existsSync(fullPath)) {
+    throw new Error(`base color file not found at ${relative(root, fullPath)}`);
+  }
+  let input;
+  try {
+    input = readJson(fullPath);
+  } catch (err) {
+    throw new Error(`base color file is not valid JSON: ${err instanceof Error ? err.message : String(err)}`);
+  }
+
+  const resolved = colorsAndTypeDir && themesDir ? null : resolveDataDirs();
+  const colorsDir = colorsAndTypeDir ?? resolved.colorsAndTypeDir;
+  const themes = themesDir ?? resolved.themesDir;
+  if (!existsSync(colorsDir)) {
+    throw new Error(`no colors and type at ${relative(root, colorsDir)}. Run the dev server once to create it.`);
+  }
+
+  const active = readActiveTheme(themes);
+  const { colorsAndType: live, source } = readLiveColorsAndType(colorsDir, active);
+
+  const { colors, report } = buildColors(input, {
+    cssVariables: live.cssVariables,
+    gradients: live.gradients,
+  });
+
+  const next = {
+    ...live,
+    ...colors,
+    updatedAt: new Date().toISOString(),
+    schemaVersion: live.schemaVersion,
+  };
+
+  const workingPath = join(colorsDir, '_working.json');
+  const saved = readSavedColorsAndType(colorsDir, active);
+
+  // Returning the buffer to what the layer under it already holds is a discard,
+  // not an edit — the same call the dev server's own PUT makes.
+  const backToSaved = saved !== null && sameContent(next, saved);
+  let wrote = null;
+  if (!dryRun) {
+    if (backToSaved) {
+      if (existsSync(workingPath)) rmSync(workingPath);
+      wrote = 'cleared';
+    } else {
+      writeFileSync(workingPath, JSON.stringify(next, null, 2) + '\n');
+      wrote = 'buffer';
+    }
+  }
+
+  return {
+    baseColorsPath: fullPath,
+    colorsAndTypeDir: colorsDir,
+    workingPath,
+    openTheme: active?.slug ?? null,
+    source,
+    // Which layer the discard compared against, so the report can name it. It
+    // is the open theme only when one is open; with none, it is the default the
+    // package ships, and calling that "the open theme" named a file nobody had
+    // opened.
+    savedSource: savedColorsAndTypeSource(active),
+    // The base color file's `name` used to pick a theme file name. This verb
+    // writes no file of its own now, so it names nothing; say so rather than
+    // drop it in silence.
+    ignoredName: input.name === undefined ? null : String(input.name),
+    dryRun,
+    wrote,
+    report,
+  };
+}
+
+export function formatSetColorsResult(result) {
+  const root = process.cwd();
+  const lines = [];
+
+  const from =
+    result.source === 'theme' && result.openTheme
+      ? `theme "${result.openTheme}"`
+      : SOURCE_LABELS[result.source];
+  const verb = result.dryRun ? 'Would replace' : 'Replaced';
+  lines.push(`${verb} the color identity, carrying everything else forward from ${from}.`);
+  if (result.ignoredName !== null) {
+    lines.push(
+      `Ignored "name": "${result.ignoredName}". The base color file no longer names a theme; ` +
+        `name it when you run save-theme.`,
+    );
+  }
+
+  lines.push(`\nContrast report (${result.report.scheme} scheme):`);
+  const width = Math.max(...result.report.checks.map((c) => c.textVar.length));
+  for (const c of result.report.checks) {
+    const mark = c.pass ? '✓' : '✗';
+    const fixed = c.corrected ? '  (auto-corrected)' : '';
+    lines.push(
+      `  ${mark} ${c.textVar.padEnd(width)}  ${c.ratio.toFixed(2).padStart(6)}:1  vs ${c.against}  floor ${c.floor}:1${fixed}`,
+    );
+  }
+  if (result.report.failures.length > 0) {
+    lines.push(`\nUnmet floors — adjust the base colors and re-run:`);
+    for (const f of result.report.failures) lines.push(`  ! ${f}`);
+  }
+
+  lines.push(
+    result.report.gradients === 'carried'
+      ? '\nGradients: kept your tuned swatch gradients.'
+      : '\nGradients: swatch tokens rebuilt from the theme families.',
+  );
+  lines.push(`Shadows: ${result.report.shadows}; carried geometry kept.`);
+  if (result.report.canvasGradient) {
+    lines.push(`Canvas sky: ${result.report.canvasGradient}.`);
+  }
+
+  if (result.wrote === 'buffer') {
+    lines.push(
+      `\nReload the app to see it. This is an unsaved edit: save the open theme in the ` +
+        `editor's Theme panel to keep it, or run save-theme to write a new one.`,
+    );
+  } else if (result.wrote === 'cleared') {
+    const held =
+      result.savedSource === 'theme' ? `theme "${result.openTheme}"` : 'the package default';
+    lines.push(
+      result.source === 'working'
+        ? `\nThat is what ${held} already holds, so the unsaved buffer was discarded. ` +
+            `Reload the app to see it.`
+        : `\nThat is what ${held} already holds, and there was no unsaved buffer, so nothing was written.`,
+    );
+  } else if (result.dryRun) {
+    lines.push(`\nDry run: nothing written under ${relative(root, result.colorsAndTypeDir)}.`);
+  }
+  return lines.join('\n');
+}

package/bin/{adjust.mjs → set-geometry.mjs}

@@ -1,19 +1,20 @@
-// `live-tokens adjust` worker.
+// `live-tokens set-geometry` worker.
 //
 // Reads an ops file (JSON), applies it to every component's LIVE config via the
-// compiled engine (dist-plugin/adjust — the CLI never imports TS sources), and
+// compiled engine (dist-plugin/setGeometry — the CLI never imports TS sources), and
 // writes the result into that component's `_working.json` buffer: the same slot
 // the editor's own edits land in, so an adjustment is an unsaved edit the user
 // saves into a theme when they want to keep it. `default.json`, named preset
 // files, themes, colors and type, and tokens.css are never touched.
 
-import { existsSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, join, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
+import { componentNames, readActiveTheme, readLiveComponentConfigs } from './lib/liveState.mjs';
+
 const pkgRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
-const ENGINE = resolve(pkgRoot, 'dist-plugin/adjust/index.js');
-const packageThemesDir = join(pkgRoot, 'src/live-tokens/data/themes');
+const ENGINE = resolve(pkgRoot, 'dist-plugin/setGeometry/index.js');
 
 const SOURCE_LABELS = {
   working: 'your unsaved edits',
@@ -30,7 +31,7 @@ const SKIP_LABELS = [
 async function loadEngine() {
   if (!existsSync(ENGINE)) {
     throw new Error(
-      `adjust engine not found at ${relative(process.cwd(), ENGINE)}. ` +
+      `setGeometry engine not found at ${relative(process.cwd(), ENGINE)}. ` +
         `Build the plugin first (npm run build:plugin).`,
     );
   }
@@ -41,10 +42,6 @@ function readJson(path) {
   return JSON.parse(readFileSync(path, 'utf8'));
 }
 
-function readJsonIfExists(path) {
-  return existsSync(path) ? readJson(path) : null;
-}
-
 /** Successive ops can touch the same alias (soften, then pill the buttons);
  *  the report shows one entry per alias, first `from` to last `to`. */
 function collapseChanges(changes) {
@@ -57,49 +54,20 @@ function collapseChanges(changes) {
   return [...byVariable.values()].filter((c) => c.from !== c.to);
 }
 
-/** The open theme, read the way every other door reads it: the local file
- *  first, then the copy the installed package ships. */
-function readActiveTheme(themesDir) {
-  if (!themesDir) return null;
-  const slug = readJsonIfExists(join(themesDir, '_active.json'))?.activeFile ?? 'default';
-  const theme =
-    readJsonIfExists(join(themesDir, `${slug}.json`)) ??
-    readJsonIfExists(join(packageThemesDir, `${slug}.json`));
-  return theme ? { slug, theme } : null;
-}
-
-/** Each component's live config, and whether a buffer or the open document
- *  answered. The document's own copy falls back to the shipped default for a
- *  component it somehow lacks, which reports as the document either way.
- *  Mirrors the dev server's `resolveLiveComponentConfig`, so the CLI adjusts
- *  what the page runs. */
-function readLiveConfigs(dir, active) {
+/** A config document names its own component, and a theme-embedded copy can
+ *  omit it, so stamp it back on before the buffer is written from it. */
+function stampedLiveConfigs(dir, active) {
+  const { configs: live, sources } = readLiveComponentConfigs(dir, active);
   const configs = {};
-  const sources = {};
-  for (const entry of readdirSync(dir, { withFileTypes: true })) {
-    if (!entry.isDirectory()) continue;
-    const comp = entry.name;
-    const componentDir = join(dir, comp);
-    const working = readJsonIfExists(join(componentDir, '_working.json'));
-    // Every theme carries every component by value, but this CLI reads the
-    // file straight off disk, ahead of any server-side fill — a theme
-    // written before this 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.
-    const embedded =
-      active?.theme?.componentConfigs?.[comp] ?? readJsonIfExists(join(componentDir, 'default.json'));
-    const config = working ?? embedded;
-    if (!config) {
-      throw new Error(`component "${comp}": default.json is missing`);
-    }
-    configs[comp] = { ...config, component: comp };
-    sources[comp] = working ? 'working' : 'theme';
+  for (const comp of componentNames(dir)) {
+    if (!live[comp]) throw new Error(`component "${comp}": default.json is missing`);
+    configs[comp] = { ...live[comp], component: comp };
   }
   return { configs, sources };
 }
 
 /** `engine` is a test seam; the CLI always runs the compiled bundle. */
-export async function runAdjust({
+export async function runSetGeometry({
   opsPath,
   dryRun = false,
   root = process.cwd(),
@@ -132,7 +100,7 @@ export async function runAdjust({
   }
 
   const active = readActiveTheme(themesDir ?? resolved?.themesDir);
-  const { configs, sources } = readLiveConfigs(dir, active);
+  const { configs, sources } = stampedLiveConfigs(dir, active);
   const now = new Date().toISOString();
   const { configs: next, report } = adjustAliases(configs, ops, now);
 
@@ -175,7 +143,7 @@ export async function runAdjust({
   };
 }
 
-export function formatAdjustResult(result) {
+export function formatSetGeometryResult(result) {
   const root = process.cwd();
   const lines = [];
   const { components: changedCount, aliases, skips } = result.totals;
@@ -192,7 +160,7 @@ export function formatAdjustResult(result) {
   }
   if (result.ignoredName !== null) {
     lines.push(
-      `Ignored "name": "${result.ignoredName}". adjust edits the open buffer now, ` +
+      `Ignored "name": "${result.ignoredName}". set-geometry edits the open buffer, ` +
         `so it writes no file of its own.`,
     );
   }