@motion-proto/live-tokens 0.52.1 → 0.53.0

package/src/editor/core/themes/lookSummary.ts

@@ -47,29 +47,7 @@ export function lookProductionState({
   };
 }
 
-/**
- * How many components run something other than what the open theme carries.
- *
- * Two facts are free on the client: whether the theme embeds a config for a
- * component, and which layer the component's live config resolves from. A
- * component the theme carries but which runs the shipped default is off it, and
- * so is a component running a buffer the theme carries nothing for. A buffer
- * over a config the theme does carry says nothing either way — that is the
- * state an apply leaves — so it stays uncounted.
- *
- * The Default theme breaks that rule: it is the one theme that embeds every
- * component's DEFAULT config by value (full set, not delta), so carrying an
- * entry says nothing. For it, off-theme is simply "buffered".
- */
-export function countComponentsOffLook(
-  components: ComponentSummary[],
-  lookConfigs: Record<string, unknown> | null | undefined,
-  lookIsDefault = false,
-): number {
-  const carried = lookConfigs ?? {};
-  return components.filter((c) => {
-    if (lookIsDefault) return c.source === 'working';
-    const inLook = Object.prototype.hasOwnProperty.call(carried, c.name);
-    return inLook ? c.source === 'default' : c.source === 'working';
-  }).length;
+/** How many components run an unsaved buffer, diverging from what the open theme carries. */
+export function countComponentsOffLook(components: ComponentSummary[]): number {
+  return components.filter((c) => c.source === 'working').length;
 }

package/src/editor/core/themes/migrateComponentConfig.ts

@@ -0,0 +1,205 @@
+/**
+ * Component-config migration, disk-shape in and disk-shape out. Extracted
+ * from `editorStore.ts` (Wave 1 of `docs/plans/theme-completeness.md`) so the
+ * server (`normalizeTheme`) can run the same migration an embedded theme
+ * config gets on the client, instead of reading it raw.
+ */
+
+import type { AliasDiskValue } from './themeTypes';
+import { runMigrations } from './migrations';
+
+/**
+ * Migrate a disk-shape alias bag through the registered migration runner.
+ *
+ * The runner is string-typed by contract (most migrations only do
+ * key/value string rewrites). Object-valued entries — currently just
+ * inline `{ kind: 'gradient', value: ... }` payloads — pass through
+ * untouched: we split the bag into string/object subsets, run the runner
+ * on the string subset, then merge.
+ *
+ * For sectiondivider's legacy 7-flat-token gradients we run a synthesis
+ * step BEFORE the migration runner that would strip those tokens. The
+ * synthesized gradient object lands in the object subset and survives
+ * the stripping pass.
+ */
+export function migrateComponentConfig(
+  component: string,
+  aliasesIn: Record<string, AliasDiskValue>,
+  rawConfig: Record<string, unknown> | undefined,
+  fileVersion: number,
+): { aliases: Record<string, AliasDiskValue>; config: Record<string, unknown> } {
+  const stringPart: Record<string, string> = {};
+  const objectPart: Record<string, AliasDiskValue> = {};
+  for (const [k, v] of Object.entries(aliasesIn)) {
+    if (typeof v === 'string') stringPart[k] = v;
+    else objectPart[k] = v;
+  }
+  // String-valued config entries join the migration input so a migration can
+  // rename or relocate them. After migration the bag flows through
+  // `splitAliasesAndConfig` which routes KNOWN keys back to config and the
+  // rest to aliases — this is what lets a migration *move* a key from the
+  // config bucket to the aliases bucket by also removing it from KNOWN.
+  // Config wins over an aliases-bucket collision on the same key: the legacy
+  // single-bucket → split-bucket move preserved "explicit config field beats
+  // legacy alias-bucketed value", and that contract still holds.
+  // Non-string config values (rare; reserved for future structured payloads)
+  // pass through untouched.
+  const configOut: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(rawConfig ?? {})) {
+    if (typeof v === 'string') stringPart[k] = v;
+    else configOut[k] = v;
+  }
+  if (component === 'sectiondivider') {
+    synthesizeSectionDividerGradients(stringPart, objectPart);
+  }
+  const migratedString = runMigrations('component-config', fileVersion, stringPart, { component });
+  const migratedObject = component === 'sectiondivider'
+    ? renameSectionDividerObjectSlots(objectPart)
+    : objectPart;
+  return {
+    aliases: { ...migratedString, ...migratedObject },
+    config: configOut,
+  };
+}
+
+/**
+ * v8→v9 companion to `componentMigration_2026_05_20_sectiondividerSlimVariants`:
+ * the structured background payload is reshaped from six color families →
+ * three size variants (lg/md/sm). Canvas's gradient is taken as the canonical
+ * seed and fanned across all three new variants; other families' gradients
+ * are dropped. Idempotent — keys already at the final shape pass through.
+ *
+ * Sources accepted (in priority order, first-found wins for canvas's slot):
+ *   --sectiondivider-canvas-background  (current/in-progress shape)
+ *   --sectiondivider-canvas-gradient    (v7-era shape)
+ *   --sectiondivider-color-canvas-background  (intermediate shape that landed
+ *                                              briefly during the color-prop pivot)
+ *
+ * The migration runner only sees string keys, so this object-shape rename
+ * has to live alongside the runner call.
+ */
+const FAMILIES = ['canvas', 'neutral', 'alternate', 'primary', 'accent', 'special'] as const;
+const SIZE_VARIANTS = ['lg', 'md', 'sm'] as const;
+function renameSectionDividerObjectSlots(
+  objectPart: Record<string, AliasDiskValue>,
+): Record<string, AliasDiskValue> {
+  // Find canvas's gradient under any historical key shape.
+  const canvasSourceKeys = [
+    '--sectiondivider-canvas-background',
+    '--sectiondivider-canvas-gradient',
+    '--sectiondivider-color-canvas-background',
+  ];
+  let canvasGradient: AliasDiskValue | undefined;
+  for (const key of canvasSourceKeys) {
+    if (objectPart[key] !== undefined) {
+      canvasGradient = objectPart[key];
+      break;
+    }
+  }
+
+  // If we found a canvas gradient (any era), fan it into the three new
+  // per-variant background slots and drop every other family's gradient.
+  // If no canvas gradient is found, pass through non-family keys verbatim
+  // so non-migration data (theme tokens, other components) isn't touched.
+  const out: Record<string, AliasDiskValue> = {};
+  for (const [key, value] of Object.entries(objectPart)) {
+    // Skip any sectiondivider per-family gradient; the canvas fan-out emits
+    // the canonical set below.
+    let isFamilyGradient = false;
+    for (const f of FAMILIES) {
+      if (
+        key === `--sectiondivider-${f}-background`
+        || key === `--sectiondivider-${f}-gradient`
+        || key === `--sectiondivider-color-${f}-background`
+      ) {
+        isFamilyGradient = true;
+        break;
+      }
+    }
+    // Pass through anything that's already at the final lg/md/sm shape so
+    // re-running the migration is idempotent.
+    if (isFamilyGradient) continue;
+    out[key] = value;
+  }
+  if (canvasGradient !== undefined) {
+    for (const v of SIZE_VARIANTS) {
+      out[`--sectiondivider-${v}-background`] = canvasGradient;
+    }
+  }
+  return out;
+}
+
+/** SectionDivider variants that ship gradient aliases. */
+const SECTIONDIVIDER_VARIANTS = ['canvas', 'neutral', 'alternate', 'primary', 'accent', 'special'] as const;
+
+/**
+ * Collapse legacy 7-flat-token gradients (`{angle, stop-{1,2,3}-{color,position}}`)
+ * for each sectiondivider variant into one structured gradient alias at
+ * `--sectiondivider-{v}-gradient`. The flat tokens stay in `stringPart`
+ * for the migration runner to strip; the structured payload joins
+ * `objectPart` so the merge produces the new shape.
+ *
+ * Skips variants that already declare a gradient alias (object form) so
+ * round-tripping doesn't overwrite user edits.
+ */
+function synthesizeSectionDividerGradients(
+  stringPart: Record<string, string>,
+  objectPart: Record<string, AliasDiskValue>,
+): void {
+  const GRADIENT_ANGLE_TOKENS: Record<string, number> = {
+    '--gradient-angle-horizontal': 90,
+    '--gradient-angle-vertical': 180,
+    '--gradient-angle-diagonal': 135,
+    '--gradient-angle-counter-diagonal': 45,
+  };
+  const GRADIENT_STOP_POSITIONS: Record<string, number> = {
+    '--gradient-stop-start': 0,
+    '--gradient-stop-mid': 50,
+    '--gradient-stop-end': 100,
+  };
+  const parseAngle = (raw: string | undefined): number => {
+    if (!raw) return 135;
+    if (raw.startsWith('--')) return GRADIENT_ANGLE_TOKENS[raw] ?? 135;
+    const m = raw.match(/^(-?\d+(?:\.\d+)?)\s*deg$/i);
+    return m ? parseFloat(m[1]) : 135;
+  };
+  const parsePosition = (raw: string | undefined, fallback: number): number => {
+    if (!raw) return fallback;
+    if (raw.startsWith('--')) return GRADIENT_STOP_POSITIONS[raw] ?? fallback;
+    const m = raw.match(/^(-?\d+(?:\.\d+)?)\s*%$/);
+    return m ? parseFloat(m[1]) : fallback;
+  };
+  const parseStopColor = (raw: string | undefined): { color: string; opacity?: number } | null => {
+    if (!raw) return null;
+    if (raw.startsWith('--')) return { color: raw };
+    const mix = raw.match(/^color-mix\(\s*in\s+srgb\s*,\s*var\((--[a-z0-9-]+)\)\s+([\d.]+)%\s*,\s*transparent\s*\)$/i);
+    if (mix) return { color: mix[1], opacity: parseFloat(mix[2]) };
+    return null;
+  };
+  for (const v of SECTIONDIVIDER_VARIANTS) {
+    const slot = `--sectiondivider-${v}-gradient`;
+    if (slot in objectPart) continue;
+    const angleKey = `${slot}-angle`;
+    const has1 = stringPart[`${slot}-stop-1-color`] !== undefined;
+    const has2 = stringPart[`${slot}-stop-2-color`] !== undefined;
+    const has3 = stringPart[`${slot}-stop-3-color`] !== undefined;
+    if (!has1 && !has2 && !has3) continue;
+    const stops: { position: number; color: string; opacity?: number }[] = [];
+    const positionDefaults = [0, 50, 100];
+    for (let i = 1; i <= 3; i++) {
+      const c = parseStopColor(stringPart[`${slot}-stop-${i}-color`]);
+      if (!c) continue;
+      const pos = parsePosition(stringPart[`${slot}-stop-${i}-position`], positionDefaults[i - 1]);
+      stops.push({ position: pos, color: c.color, ...(c.opacity !== undefined ? { opacity: c.opacity } : {}) });
+    }
+    if (stops.length < 2) continue;
+    objectPart[slot] = {
+      kind: 'gradient',
+      value: {
+        type: 'linear',
+        angle: parseAngle(stringPart[angleKey]),
+        stops,
+      },
+    };
+  }
+}

package/src/editor/core/themes/migrations/2026-05-19-sectiondivider-rich-gradient.ts

@@ -7,7 +7,7 @@ import type { Migration } from './index';
  * carrying `{type, angle, stops[]}` inline on the component slice.
  *
  * The structured value is synthesized *before* this migration runs — see
- * `synthesizeSectionDividerGradients` in `editorStore.ts`. The synthesizer
+ * `synthesizeSectionDividerGradients` in `migrateComponentConfig.ts`. The synthesizer
  * walks the legacy 7-token shape and emits a `kind: 'gradient'` alias into
  * the load path's object subset, where it survives this stripping pass and
  * lands in the in-memory slice.

package/src/editor/core/themes/migrations/2026-05-20-sectiondivider-slim-variants.ts

@@ -18,7 +18,7 @@ import type { Migration } from './index';
  *   `*-padding`            → `*-spacing`
  *
  * The structured background payload moves through a companion rename in
- * `migrateComponentAliases` (editorStore.ts), since the runner only sees
+ * `migrateComponentConfig` (migrateComponentConfig.ts), since the runner only sees
  * string keys.
  */
 const FAMILIES = ['canvas', 'neutral', 'alternate', 'primary', 'accent', 'special'] as const;

package/src/editor/core/themes/migrations/2026-05-22-sectiondivider-intrinsics-to-css.ts

@@ -24,7 +24,7 @@ import type { Migration } from './index';
  *   - both undefined                     → emit nothing (default 'none' applies via CSS)
  *   - `show-hairline` unset but a real position exists → preserve the position
  *
- * The migration touches the unified bag produced by `migrateComponentAliases`
+ * The migration touches the unified bag produced by `migrateComponentConfig`
  * (which now pre-merges string-valued config entries). The post-migration
  * `splitAliasesAndConfig` step routes the new keys to `aliases` (since
  * `KNOWN_COMPONENT_CONFIG_KEYS` no longer contains them) while keeping

package/src/editor/core/themes/parsers/gradient.ts

@@ -0,0 +1,211 @@
+/**
+ * The single source of truth for the CSS form of a structured gradient value.
+ * A component alias that owns a gradient serializes to one of two shapes:
+ *
+ *   linear-gradient(<angle>deg, <stop>, <stop>, …)
+ *   radial-gradient(<shape> at <cx>% 50%, <stop>, <stop>, …)
+ *
+ * `solid` and `none` are NOT represented here. `solid` renders as its first
+ * stop's colour and `none` as `transparent`, both indistinguishable in CSS
+ * from an ordinary colour alias, so `parseGradientValue` never claims them —
+ * see the round-trip contract below. Everything that writes or reads this form
+ * must go through `formatGradientValue` / `parseGradientValue` so the shape
+ * lives in exactly one place.
+ *
+ * ## Round-trip contract
+ *
+ * `formatGradientValue(parseGradientValue(css)) === css` for every string
+ * `formatGradientValue` can emit. The reverse holds only up to CSS
+ * equivalence: the format drops decompositions that have no rendered meaning,
+ * so parsing returns the canonical member of the equivalence class.
+ *
+ *   - A radial's `angle` is never emitted (it exists so toggling the type back
+ *     to linear restores the user's angle), so it parses back as 0.
+ *   - `centerX: 50` and an absent `centerX` both emit `at 50% 50%`; parsing
+ *     returns the absent form.
+ *   - An ellipse emits `radius * aspectX` and `radius * aspectY`, three
+ *     unknowns in two numbers. `radius` is vestigial (no setter writes it and
+ *     `GradientSourceSnapshot` has no field for it), so parsing folds it into
+ *     the aspects against `RADIAL_BASE_PX`. The two emitted numbers are
+ *     unchanged, which is all CSS sees.
+ *
+ * This module depends only on its sibling `colorOpacity` parser, so the
+ * dev-server vite plugin (a separate build) can import it the same way it
+ * imports `globalRootBlock`.
+ */
+import { parseColorOpacity, formatColorOpacity } from './colorOpacity';
+
+export interface GradientStop {
+  /** 0–100 percentage along the gradient axis. */
+  position: number;
+  /** A design-token name (`--surface-neutral-low`) or a raw CSS colour. */
+  color: string;
+  /** 0–100 alpha. Absent means 100. */
+  opacity?: number;
+  /** `false` marks the stop an explicit off-palette override: the stop picker
+   *  opens to any colour rather than the current family, and a family-swap
+   *  rewrite skips the stop so its colour survives. Absent means `true`.
+   *  It has no CSS form, so `parseGradientValue` never produces it and
+   *  `formatGradientValue` ignores it. It lives on the shared stop because
+   *  the persisted stop carries it. */
+  monochrome?: boolean;
+}
+
+export interface GradientValue {
+  type: 'linear' | 'radial' | 'solid' | 'none';
+  angle: number;
+  radius?: number;
+  centerX?: number;
+  aspectX?: number;
+  aspectY?: number;
+  stops: GradientStop[];
+}
+
+/** Base radius (px) an ellipse's aspect factors scale, when the gradient has
+ *  no explicit `radius` but needs concrete dimensions to express its shape.
+ *  A pleasant mid-size that reads as a soft glow inside typical component
+ *  containers. */
+export const RADIAL_BASE_PX = 100;
+
+/** Resolve a stop's colour + opacity into a CSS colour value without the
+ *  trailing `${position}%`. Shared by the stop formatter (which appends the
+ *  position) and the solid path (which doesn't). */
+function formatStopColor(s: GradientStop): string {
+  const opacity = s.opacity ?? 100;
+  if (s.color.startsWith('--')) {
+    return opacity >= 100 ? `var(${s.color})` : formatColorOpacity(s.color, opacity);
+  }
+  // A raw colour is not a design token, so colorOpacity, which owns the token
+  // form, cannot express it.
+  return opacity >= 100 ? s.color : `color-mix(in srgb, ${s.color} ${opacity}%, transparent)`;
+}
+
+/** Stops portion only, for callers that supply their own gradient function
+ *  wrapper (the palette selector overrides the angle per slot while keeping
+ *  the token's stop list and its `var(--color-…)` refs). */
+export function formatGradientStops(stops: readonly GradientStop[]): string {
+  return stops.map((s) => `${formatStopColor(s)} ${s.position}%`).join(', ');
+}
+
+function formatRadialShape(v: GradientValue): string {
+  const ax = v.aspectX ?? 1;
+  const ay = v.aspectY ?? 1;
+  if (ax === 1 && ay === 1) {
+    return v.radius && v.radius > 0 ? `circle ${v.radius}px` : 'circle';
+  }
+  const base = v.radius && v.radius > 0 ? v.radius : RADIAL_BASE_PX;
+  return `ellipse ${(base * ax).toFixed(2)}px ${(base * ay).toFixed(2)}px`;
+}
+
+/** Serialize a structured gradient value (theme token or component-owned)
+ *  into a CSS background declaration.
+ *  - `none`   → `transparent` (no background paint).
+ *  - `solid`  → the first stop's colour (no gradient function).
+ *  - `linear` → `linear-gradient(<angle>deg, <stops>)`.
+ *  - `radial` → `radial-gradient(<shape> at <centerX>% 50%, <stops>)`, where
+ *    shape is `circle [radius]` at aspect 1 and `ellipse rx ry` otherwise.
+ *    Aspects are independent stretch factors, not an area-preserving ratio:
+ *    both at 8 is a circle eight times the size of both at 1. */
+export function formatGradientValue(v: GradientValue): string {
+  if (v.type === 'none') return 'transparent';
+  if (v.type === 'solid') {
+    const first = v.stops[0];
+    return first ? formatStopColor(first) : 'transparent';
+  }
+  const stops = formatGradientStops(v.stops);
+  if (v.type === 'linear') return `linear-gradient(${v.angle}deg, ${stops})`;
+  return `radial-gradient(${formatRadialShape(v)} at ${v.centerX ?? 50}% 50%, ${stops})`;
+}
+
+const NUM = String.raw`-?\d+(?:\.\d+)?`;
+const LINEAR_RE = new RegExp(String.raw`^linear-gradient\(\s*(${NUM})deg\s*,\s*(.+)\)$`, 'i');
+const RADIAL_RE = new RegExp(
+  String.raw`^radial-gradient\(\s*(circle|circle\s+${NUM}px|ellipse\s+${NUM}px\s+${NUM}px)\s+at\s+(${NUM})%\s+50%\s*,\s*(.+)\)$`,
+  'i',
+);
+const STOP_RE = new RegExp(String.raw`^(.*?)\s+(${NUM})%$`);
+const CIRCLE_RADIUS_RE = new RegExp(String.raw`^circle\s+(${NUM})px$`, 'i');
+const ELLIPSE_RE = new RegExp(String.raw`^ellipse\s+(${NUM})px\s+(${NUM})px$`, 'i');
+const VAR_RE = /^var\((--[a-z0-9-]+)\)$/i;
+
+/** Split on top-level separators only. Stop colours nest commas inside
+ *  `color-mix(…)`, so a plain `split(',')` shreds them. */
+function splitTopLevel(s: string): string[] {
+  const parts: string[] = [];
+  let depth = 0;
+  let start = 0;
+  for (let i = 0; i < s.length; i++) {
+    const c = s[i];
+    if (c === '(') depth++;
+    else if (c === ')') depth--;
+    else if (c === ',' && depth === 0) {
+      parts.push(s.slice(start, i));
+      start = i + 1;
+    }
+  }
+  parts.push(s.slice(start));
+  return parts;
+}
+
+function parseStop(raw: string): GradientStop | null {
+  const m = raw.trim().match(STOP_RE);
+  if (!m) return null;
+  const position = parseFloat(m[2]);
+  const color = m[1].trim();
+  const opacity = parseColorOpacity(color);
+  if (opacity) return { position, color: opacity.name, opacity: opacity.opacity };
+  const token = color.match(VAR_RE);
+  return { position, color: token ? token[1] : color };
+}
+
+function parseStops(raw: string): GradientStop[] | null {
+  const stops: GradientStop[] = [];
+  for (const part of splitTopLevel(raw)) {
+    const stop = parseStop(part);
+    if (!stop) return null;
+    stops.push(stop);
+  }
+  return stops.length > 0 ? stops : null;
+}
+
+function parseRadialShape(raw: string): Pick<GradientValue, 'radius' | 'aspectX' | 'aspectY'> | null {
+  const shape = raw.trim();
+  if (/^circle$/i.test(shape)) return {};
+  const circle = shape.match(CIRCLE_RADIUS_RE);
+  if (circle) return { radius: parseFloat(circle[1]) };
+  const ellipse = shape.match(ELLIPSE_RE);
+  if (!ellipse) return null;
+  // Aspects of exactly 1 are dropped, matching `setGradientAspect`, so the
+  // parsed value stays the canonical minimal shape.
+  const ax = parseFloat(ellipse[1]) / RADIAL_BASE_PX;
+  const ay = parseFloat(ellipse[2]) / RADIAL_BASE_PX;
+  return { ...(ax === 1 ? {} : { aspectX: ax }), ...(ay === 1 ? {} : { aspectY: ay }) };
+}
+
+/**
+ * Recover a structured gradient from the CSS `formatGradientValue` emits.
+ * Returns null for anything else, including the plain colour a `solid` or
+ * `none` gradient renders as: claiming those would turn every ordinary colour
+ * alias into a gradient object.
+ */
+export function parseGradientValue(value: string): GradientValue | null {
+  const css = value.trim();
+  const linear = css.match(LINEAR_RE);
+  if (linear) {
+    const stops = parseStops(linear[2]);
+    return stops && { type: 'linear', angle: parseFloat(linear[1]), stops };
+  }
+  const radial = css.match(RADIAL_RE);
+  if (!radial) return null;
+  const shape = parseRadialShape(radial[1]);
+  const stops = parseStops(radial[3]);
+  if (!shape || !stops) return null;
+  const centerX = parseFloat(radial[2]);
+  return {
+    type: 'radial',
+    angle: 0,
+    ...shape,
+    ...(centerX === 50 ? {} : { centerX }),
+    stops,
+  };
+}

package/src/editor/core/themes/slices/gradients.ts

@@ -4,9 +4,12 @@
  * (`--color-brand-500`); the renderer wraps them in `var(...)` so palette
  * edits flow through.
  */
-import type { EditorState, GradientToken, GradientTokenStop, GradientType, GradientAliasValue } from '../../store/editorTypes';
+import type { EditorState, GradientToken, GradientTokenStop, GradientType } from '../../store/editorTypes';
 import type { GradientDiskToken } from '../themeTypes';
 import { mutate } from '../../store/editorCore';
+import { formatGradientValue, formatGradientStops as formatStopList } from '../parsers/gradient';
+
+export { formatGradientValue };
 
 export function makeDefaultGradients(): GradientToken[] {
   return [
@@ -70,67 +73,11 @@ export function loadGradientsFromFile(
   if (matches) next.gradients.tokens = structuredClone(gradients) as GradientToken[];
 }
 
-function formatGradientStop(s: GradientTokenStop): string {
-  return `${formatGradientStopColor(s)} ${s.position}%`;
-}
-
 /** Stops portion only — used by the palette selector to materialize a
  *  linear-gradient with a per-slot angle override while keeping the token's
  *  stop list (and its `var(--color-…)` refs, which propagate palette edits). */
 export function formatGradientStops(t: GradientToken): string {
-  return t.stops.map(formatGradientStop).join(', ');
-}
-
-/** Serialize a structured gradient value (theme token or component-owned)
- *  into a CSS background declaration.
- *  - `none`   → `transparent` (no background paint).
- *  - `solid`  → the first stop's color (no gradient function).
- *  - `linear` → `linear-gradient(<angle>, <stops>)`.
- *  - `radial` → `radial-gradient(<shape> at <centerX>% 50%, <stops>)`.
- *               centerX defaults to 50. Shape is `circle [radius]` when the
- *               aspect ratio is 1 (or absent); for aspect ≠ 1 we emit
- *               `ellipse rx ry` anchored to `radius || 100px`, area-preserved
- *               so the R=1 boundary is continuous with the legacy circle. */
-export function formatGradientValue(v: GradientAliasValue): string {
-  if (v.type === 'none') return 'transparent';
-  if (v.type === 'solid') {
-    const first = v.stops[0];
-    if (!first) return 'transparent';
-    return formatGradientStopColor(first);
-  }
-  const stops = v.stops.map(formatGradientStop).join(', ');
-  if (v.type === 'linear') return `linear-gradient(${v.angle}deg, ${stops})`;
-  const cx = v.centerX ?? 50;
-  return `radial-gradient(${formatRadialShape(v)} at ${cx}% 50%, ${stops})`;
-}
-
-/** Default base radius (px) when the gradient has no explicit `radius` but
- *  needs concrete dimensions to express its aspect ratio. Chosen as a
- *  pleasant-looking mid-size that reads as a "soft glow" inside typical
- *  component containers; the user can dial `radius` to override. */
-const DEFAULT_RADIAL_BASE_PX = 100;
-
-function formatRadialShape(v: GradientAliasValue): string {
-  const ax = v.aspectX ?? 1;
-  const ay = v.aspectY ?? 1;
-  if (ax === 1 && ay === 1) {
-    return v.radius && v.radius > 0 ? `circle ${v.radius}px` : 'circle';
-  }
-  const base = v.radius && v.radius > 0 ? v.radius : DEFAULT_RADIAL_BASE_PX;
-  const rx = base * ax;
-  const ry = base * ay;
-  return `ellipse ${rx.toFixed(2)}px ${ry.toFixed(2)}px`;
-}
-
-/** Resolve a stop's color + opacity into a CSS color value without the
- *  trailing `${position}%`. Shared by the gradient-stop formatter (which
- *  appends the position) and the solid path (which doesn't). */
-function formatGradientStopColor(s: GradientTokenStop): string {
-  const base = s.color.startsWith('--') ? `var(${s.color})` : s.color;
-  const opacity = s.opacity ?? 100;
-  return opacity >= 100
-    ? base
-    : `color-mix(in srgb, ${base} ${opacity}%, transparent)`;
+  return formatStopList(t.stops);
 }
 
 function formatGradient(t: GradientToken): string {

package/src/editor/core/themes/themeService.ts

@@ -1,15 +1,19 @@
-import type { Theme, ThemeMeta, ThemeBundle, ColorsAndType, ComponentConfig } from './themeTypes';
+import type { Theme, ThemeMeta, ThemeBundle, ColorsAndType, ComponentConfig, ThemeFillReport } from './themeTypes';
 import { versionedFileResource } from '../storage/files/versionedFileResourceClient';
 import { API_BASE } from '../storage/apiBase';
 import { liveMovedSinceBake } from '../productionPulse';
 import { listComponents, getActiveComponentConfig } from '../components/componentConfigService';
 import { getActiveColorsAndType } from './colorsAndTypeService';
 import { broadcastAppliedTheme, hydrateAppliedTheme } from './themeDocumentSync';
+import { CURRENT_COMPONENT_SCHEMA_VERSION } from './migrations';
+import { THEME_SCHEMA_VERSION } from './themeTypes';
+
+export type { ThemeFillReport };
 
 /**
  * REST client for theme files, the documents of the editor. A theme carries a
  * whole look by value: the colors and type plus a config for every component
- * that is off its default. One theme is open (`themes/_active.json`) and one is
+ * this install has. One theme is open (`themes/_active.json`) and one is
  * published (`themes/_production.json`); the live look is the open theme plus
  * whatever the `_working` buffers hold over it.
  *
@@ -61,6 +65,9 @@ export interface ApplyThemeResult {
   componentConfigs: Record<string, ComponentConfig>;
   /** Components the theme carries data for that this install doesn't have. */
   skippedComponents: string[];
+  /** What the completeness fill (`normalizeTheme`) had to add to reach this
+   *  theme, reported so the panel can name it. */
+  filled: ThemeFillReport;
 }
 
 /**
@@ -128,8 +135,9 @@ function withoutLiveMarkers<T extends { _fileName?: string; _source?: unknown }>
 
 /**
  * The look as it stands: the live colors and type plus the live config of
- * every component that sits off its default, all by value. Delta encoding — a
- * component absent from the map runs the local default, which stays canonical.
+ * every component this install has, all by value. A theme is a complete
+ * document (`docs/plans/theme-completeness.md`), so the capture carries every
+ * component, not just the ones off their default.
  *
  * Everything comes from the live read doors, so a capture takes the buffers
  * over the open theme's own copies. The colors and type are normalised on the
@@ -141,10 +149,10 @@ async function captureLook(): Promise<Pick<Theme, 'colorsAndType' | 'componentCo
   if (!liveColorsAndType) {
     throw new Error('No live colors and type to capture');
   }
-  const overridden = (await listComponents()).filter((c) => c.source !== 'default');
-  const configs = await Promise.all(overridden.map((c) => getActiveComponentConfig(c.name)));
+  const components = await listComponents();
+  const configs = await Promise.all(components.map((c) => getActiveComponentConfig(c.name)));
   const componentConfigs: Record<string, ComponentConfig> = {};
-  overridden.forEach((c, i) => {
+  components.forEach((c, i) => {
     const config = configs[i];
     if (config) componentConfigs[c.name] = withoutLiveMarkers(config);
   });
@@ -166,7 +174,8 @@ export async function saveAsTheme(
     name: displayName,
     createdAt: now,
     updatedAt: now,
-    schemaVersion: 3,
+    schemaVersion: THEME_SCHEMA_VERSION,
+    componentSchemaVersion: CURRENT_COMPONENT_SCHEMA_VERSION,
     ...look,
   });
   liveMovedSinceBake.set(true);
@@ -188,7 +197,8 @@ export async function saveActiveTheme(displayName?: string): Promise<void> {
     name: displayName ?? active.name,
     createdAt: active.createdAt,
     updatedAt: new Date().toISOString(),
-    schemaVersion: 3,
+    schemaVersion: THEME_SCHEMA_VERSION,
+    componentSchemaVersion: CURRENT_COMPONENT_SCHEMA_VERSION,
     ...look,
   });
   liveMovedSinceBake.set(true);
@@ -203,6 +213,9 @@ export interface ImportThemeResult {
   /** Refs a v1 bundle failed to carry, as `colors-and-type:<name>` /
    *  `<comp>/<name>`. Each fell back to the default. */
   dropped: string[];
+  /** What the completeness fill (`normalizeTheme`) had to add to reach this
+   *  theme, reported so the panel can name it. */
+  filled: ThemeFillReport;
 }
 
 /**