@motion-proto/live-tokens 0.49.1 → 0.50.0

package/src/editor/core/fonts/fontWeightAvailability.ts

@@ -0,0 +1,97 @@
+import type { FontFamily, FontSource, FontStack } from '../themes/themeTypes';
+
+export interface FontWeightAvailability {
+  familyName: string;
+  weights: ReadonlySet<number>;
+}
+
+/** Typography tokens consistently pair `-font-weight` with `-font-family`. */
+export function inferFontFamilyVariable(weightVariable: string): string | null {
+  return weightVariable.endsWith('-font-weight')
+    ? `${weightVariable.slice(0, -'-font-weight'.length)}-font-family`
+    : null;
+}
+
+function normalizeFamilyName(value: string): string {
+  let name = value.trim();
+  // Imported font metadata sometimes retains more than one layer of wrapping
+  // quotes (for example `"Comfortaa"`). Peel all balanced wrappers so it can
+  // still be compared with a computed font-family value.
+  while (
+    name.length >= 2
+    && ((name.startsWith('"') && name.endsWith('"'))
+      || (name.startsWith("'") && name.endsWith("'")))
+  ) {
+    name = name.slice(1, -1).trim();
+  }
+  return name.toLocaleLowerCase();
+}
+
+function firstFamily(value: string): string {
+  let quote: '"' | "'" | null = null;
+  for (let i = 0; i < value.length; i += 1) {
+    const char = value[i];
+    if (quote) {
+      if (char === quote && value[i - 1] !== '\\') quote = null;
+      continue;
+    }
+    if (char === '"' || char === "'") {
+      quote = char;
+      continue;
+    }
+    if (char === ',') return value.slice(0, i);
+  }
+  return value;
+}
+
+function familyMap(sources: FontSource[]): Map<string, FontFamily> {
+  const families = new Map<string, FontFamily>();
+  for (const source of sources) {
+    for (const family of source.families) {
+      families.set(normalizeFamilyName(family.cssName), family);
+      families.set(normalizeFamilyName(family.name), family);
+    }
+  }
+  return families;
+}
+
+function knownAvailability(family: FontFamily | undefined): FontWeightAvailability | null {
+  if (!family?.weights?.length) return null;
+  return {
+    familyName: family.name,
+    weights: new Set(family.weights),
+  };
+}
+
+/**
+ * Find the declared weights for the primary face in a CSS font-family value.
+ * Returns null for system fonts and sources whose available weights are not
+ * known, so the editor never disables an option on incomplete metadata.
+ */
+export function fontWeightAvailability(
+  fontFamilyValue: string,
+  sources: FontSource[],
+  stacks: FontStack[],
+): FontWeightAvailability | null {
+  const families = familyMap(sources);
+  const stackRef = fontFamilyValue.match(/^\s*var\(\s*(--font-(?:display|sans|serif|mono))\b/);
+
+  if (stackRef) {
+    const stack = stacks.find((candidate) => candidate.variable === stackRef[1]);
+    for (const slot of stack?.slots ?? []) {
+      if (slot.kind === 'project') {
+        const family = sources.flatMap((source) => source.families)
+          .find((candidate) => candidate.id === slot.familyId);
+        if (!family) continue;
+        return knownAvailability(family);
+      }
+      // A system or generic slot is a real primary face, but has no reliable
+      // per-weight metadata. Do not make assumptions from later fallbacks.
+      return null;
+    }
+    return null;
+  }
+
+  const name = normalizeFamilyName(firstFamily(fontFamilyValue));
+  return knownAvailability(families.get(name));
+}

package/src/editor/core/preview/lookPreview.ts

@@ -2,8 +2,8 @@ import { get } from 'svelte/store';
 import type { FontSource, Theme, ColorsAndType } from '../themes/themeTypes';
 import { editorState, colorsAndTypeToState, toComponentSlice } from '../store/editorStore';
 import { deriveCssVars } from '../store/editorRenderer';
-import { setCssVar, removeCssVar } from '../cssVarSync';
-import { applyFontSources, resolveFontStackValues } from '../fonts/fontLoader';
+import { batchCssVarChanges, setCssVar, removeCssVar } from '../cssVarSync';
+import { applyFontSources } from '../fonts/fontLoader';
 import { migrateColorsAndTypeFonts } from '../fonts/fontMigration';
 import { loadTheme } from '../themes/themeService';
 
@@ -50,7 +50,6 @@ export function themeLook(theme: Theme, defaults: Theme): RenderedLook {
     state.components[comp] = toComponentSlice(comp, config.aliases, config.config, config.schemaVersion);
   }
   const vars = deriveCssVars(state);
-  Object.assign(vars, resolveFontStackValues(colorsAndType.fontStacks ?? [], colorsAndType.fontSources ?? []));
   return { vars, fontSources: colorsAndType.fontSources ?? [] };
 }
 
@@ -65,7 +64,6 @@ export function colorsAndTypeLook(colorsAndType: ColorsAndType): RenderedLook {
   const next = structuredClone(colorsAndType);
   migrateColorsAndTypeFonts(next);
   const vars = deriveCssVars(colorsAndTypeToState(next));
-  Object.assign(vars, resolveFontStackValues(next.fontStacks ?? [], next.fontSources ?? []));
   return { vars, fontSources: next.fontSources ?? [] };
 }
 
@@ -73,7 +71,6 @@ export function colorsAndTypeLook(colorsAndType: ColorsAndType): RenderedLook {
 export function liveLook(): RenderedLook {
   const state = get(editorState);
   const vars = deriveCssVars(state);
-  Object.assign(vars, resolveFontStackValues(state.fonts.stacks, state.fonts.sources));
   return { vars, fontSources: state.fonts.sources };
 }
 
@@ -91,24 +88,24 @@ function loadDefaults(): Promise<Theme> {
 }
 
 function paint(next: RenderedLook, from: RenderedLook): void {
-  for (const [name, value] of Object.entries(next.vars)) {
-    if (from.vars[name] !== value) setCssVar(name, value);
-  }
-  for (const name of Object.keys(from.vars)) {
-    if (!(name in next.vars)) removeCssVar(name);
-  }
-  applyFontSources(next.fontSources);
+  batchCssVarChanges(() => {
+    for (const [name, value] of Object.entries(next.vars)) {
+      if (from.vars[name] !== value) setCssVar(name, value);
+    }
+    for (const name of Object.keys(from.vars)) {
+      if (!(name in next.vars)) removeCssVar(name);
+    }
+    applyFontSources(next.fontSources);
+  });
 }
 
 /**
- * Show `look` on the page. Re-entrant: a live preview is reverted first, so
- * every look is painted as a diff against the user's real state and a var one
- * look sets but the next does not returns to its live value instead of vanishing.
- * The two passes run in one task, so the browser never paints the intermediate.
+ * Show `look` on the page. Re-entrant previews diff directly from the look
+ * already painted; only Cancel restores the live store projection. This avoids
+ * repainting the live theme as an invisible intermediate on every picker row.
  */
 function applyPreview(look: RenderedLook): void {
-  revertPreview();
-  paint(look, liveLook());
+  paint(look, livePreview ?? liveLook());
   livePreview = look;
 }
 
@@ -130,6 +127,14 @@ export function revertPreview(): void {
   livePreview = null;
 }
 
+/** Release the preview without repainting. The caller must immediately load
+ * the exact look being previewed into the store. This is the Save handoff: the
+ * selected theme is already on screen, so restoring the old live look before
+ * applying it would add work and create a visible flash across the request. */
+export function commitPreview(): void {
+  livePreview = null;
+}
+
 export function isPreviewing(): boolean {
   return livePreview !== null;
 }

package/src/editor/core/store/editorRenderer.ts

@@ -12,7 +12,8 @@
  */
 
 import type { EditorState } from './editorTypes';
-import { setCssVar, removeCssVar } from '../cssVarSync';
+import { batchCssVarChanges, setCssVar, removeCssVar } from '../cssVarSync';
+import { applyFontSources, resolveFontStackValues } from '../fonts/fontLoader';
 import { palettesToVars } from '../palettes/paletteDerivation';
 import {
   editorState,
@@ -38,10 +39,12 @@ export function deriveCssVars(state: EditorState): Record<string, string> {
   }
   Object.assign(out, palettesToVars(state.palettes));
   Object.assign(out, componentsToVars(state.components));
+  Object.assign(out, resolveFontStackValues(state.fonts.stacks, state.fonts.sources));
   return out;
 }
 
 let lastApplied: Record<string, string> = {};
+let lastFontSources = '';
 let installed = false;
 
 /**
@@ -55,17 +58,29 @@ export function installRenderer(): void {
   if (typeof window === 'undefined') return;
   editorState.subscribe((state) => {
     const next = deriveCssVars(state);
-    for (const name in next) {
-      if (next[name] !== lastApplied[name]) setCssVar(name, next[name]);
-    }
-    for (const name in lastApplied) {
-      if (!(name in next)) removeCssVar(name);
-    }
+    batchCssVarChanges(() => {
+      for (const name in next) {
+        if (next[name] !== lastApplied[name]) setCssVar(name, next[name]);
+      }
+      for (const name in lastApplied) {
+        if (!(name in next)) removeCssVar(name);
+      }
+    });
     lastApplied = next;
+
+    // Font source nodes are DOM state just like root custom properties. Keep
+    // them behind the same authoritative store subscription so load,
+    // undo/redo, reset, and every future mutation path all reconcile them.
+    const nextFontSources = JSON.stringify(state.fonts.sources);
+    if (nextFontSources !== lastFontSources) {
+      applyFontSources(state.fonts.sources);
+      lastFontSources = nextFontSources;
+    }
   });
 }
 
 /** Test-only: clear the diff cache so independent test runs don't leak applied vars. */
 export function __resetRendererCacheForTests(): void {
   lastApplied = {};
+  lastFontSources = '';
 }

package/src/editor/core/store/editorStore.ts

@@ -76,6 +76,7 @@ import {
 } from '../themes/slices/gradients';
 import {
   componentBaseline,
+  getComponentOwnedVarNames,
   loadComponentsFromVars,
   notifyComponentSavedChanged,
   setSavedComponentBaseline,
@@ -510,6 +511,36 @@ export function seedComponentsFromApi(
   schedulePersist();
 }
 
+/**
+ * Replace colors/type and every component slice as one theme transaction.
+ * Theme application used to call `loadFromFile` and `seedComponentsFromApi`
+ * separately, causing two complete renderer passes and briefly exposing a
+ * mixed old-components/new-tokens state. Build the final state first and emit
+ * it once instead.
+ */
+export function loadThemeFromApi(
+  colorsAndType: ColorsAndType,
+  configs: Record<string, ComponentSeed>,
+): void {
+  const next = colorsAndTypeToState(colorsAndType);
+  next.components = {};
+  for (const [comp, cfg] of Object.entries(configs)) {
+    const split = toComponentSlice(comp, cfg.aliases, cfg.config, cfg.schemaVersion ?? 0);
+    next.components[comp] = { aliases: { ...split.aliases }, config: { ...split.config } };
+    setSavedComponentBaseline(comp, componentBaseline(split));
+  }
+  // Defensive legacy cleanup: a colors-and-type payload may still carry
+  // component-owned variables in its catch-all bag. The component slice is
+  // authoritative for a whole-theme load.
+  for (const name of getComponentOwnedVarNames(next)) delete next.cssVars[name];
+
+  resetHistoryForLoad();
+  store.set(next);
+  markColorsAndTypeSaved(next);
+  notifyComponentSavedChanged();
+  schedulePersist();
+}
+
 // ── Colors and type load / save ────────────────────────────────────────────
 
 /**

package/src/editor/core/store/gradientSource.ts

@@ -40,6 +40,9 @@ export interface GradientSourceSnapshot {
 }
 
 export interface GradientSource {
+  /** CSS variable ultimately written by this source. Exposed for editor
+   *  semantics and automated control-to-runtime contract discovery. */
+  targetVariable: string;
   /** Reactive readable of the current gradient value (or undefined if missing). */
   current: Readable<GradientSourceSnapshot | undefined>;
   setAll(next: GradientSourceSnapshot): void;
@@ -67,6 +70,7 @@ export function colorsAndTypeGradientSource(variable: string): GradientSource {
     };
   });
   return {
+    targetVariable: variable,
     current,
     setAll: (next) => setGradient(variable, next),
     setType: (t) => setGradientType(variable, t),
@@ -158,6 +162,7 @@ export function componentGradientSource(component: string, varName: string): Gra
     });
   };
   return {
+    targetVariable: varName,
     current,
     setAll: (next) => writeComponentGradient(component, varName, {
       type: next.type,

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

@@ -8,7 +8,6 @@ import {
 import { API_BASE } from '../storage/apiBase';
 import { liveMovedSinceBake } from '../productionPulse';
 import { loadFromFile as loadEditorState, toColorsAndType, markSaved, markColorsAndTypeSaved } from '../store/editorStore';
-import { applyFontSources, applyFontStacks } from '../fonts/fontLoader';
 import { migrateColorsAndTypeFonts } from '../fonts/fontMigration';
 
 // ── API helpers ──────────────────────────────────────────────
@@ -78,18 +77,9 @@ export async function persistColorsAndType(
   markColorsAndTypeSaved(state);
 }
 
-/** Load colors and type into the editor state and re-apply font side-effects
- *  (@font-face rules + `--font-*` CSS vars on :root). */
+/** Load colors and type into the editor state. The store renderer projects
+ *  font sources, stacks, and all other CSS variables in one reactive pass. */
 export function hydrateColorsAndType(colorsAndType: ColorsAndType): void {
   migrateColorsAndTypeFonts(colorsAndType);
   loadEditorState(colorsAndType);
-  // Font data is in state.fonts via loadEditorState; the DOM-side-effect
-  // helpers still need to run so @font-face rules and --font-* CSS vars
-  // land on :root.
-  if (colorsAndType.fontSources && colorsAndType.fontSources.length > 0) {
-    applyFontSources(colorsAndType.fontSources);
-  }
-  if (colorsAndType.fontStacks && colorsAndType.fontStacks.length > 0) {
-    applyFontStacks(colorsAndType.fontStacks, colorsAndType.fontSources ?? []);
-  }
 }

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

@@ -28,7 +28,10 @@ const VARIANTS = ['lg', 'md', 'sm'] as const;
 const SUFFIX_RENAMES: Array<[RegExp, string]> = [
   [/-title-border-width$/, '-title-outline-width'],
   [/-title-stroke-color$/, '-title-outline-color'],
-  [/-padding$/, '-spacing'],
+  [
+    /^--sectiondivider-(canvas|neutral|alternate|primary|accent|special)-padding$/,
+    '--sectiondivider-$1-spacing',
+  ],
 ];
 
 function renameKeySuffix(key: string): string {

package/src/editor/core/themes/migrations/2026-05-21-sectiondivider-spacing-to-padding.ts

@@ -16,7 +16,10 @@ export const componentMigration_2026_05_21_sectiondividerSpacingToPadding: Migra
     if (meta.component !== 'sectiondivider') return { ...rawVars };
     const out: Record<string, string> = {};
     for (const [key, value] of Object.entries(rawVars)) {
-      const renamed = key.replace(/-spacing$/, '-padding');
+      const renamed = key.replace(
+        /^--sectiondivider-(lg|md|sm)-spacing$/,
+        '--sectiondivider-$1-padding',
+      );
       out[renamed] = value;
     }
     return out;

package/src/editor/core/themes/migrations/2026-05-25-cornerbadge-flatten-variants.ts

@@ -16,6 +16,7 @@ import type { Migration } from './index';
  */
 const VARIANTS = ['primary', 'accent', 'neutral', 'alternate', 'canvas', 'special', 'success', 'warning', 'danger', 'info'] as const;
 const RE = new RegExp(`^--corner-badge-(${VARIANTS.join('|')})-(.+)$`);
+const CURRENT_COLOR_PROPS = new Set(['surface', 'border', 'text']);
 
 function flattenVariants(rawVars: Record<string, string>, meta: { component?: string }): Record<string, string> {
   if (meta.component !== 'cornerbadge') return rawVars;
@@ -25,6 +26,13 @@ function flattenVariants(rawVars: Record<string, string>, meta: { component?: st
     const m = key.match(RE);
     if (m) {
       const prop = m[2];
+      // The current component composes Badge's per-variant colors under these
+      // same prefixes. They were introduced after this migration and must be
+      // left intact when an otherwise-current unversioned snapshot is loaded.
+      if (CURRENT_COLOR_PROPS.has(prop)) {
+        out[key] = value;
+        continue;
+      }
       if (!collected.has(prop)) collected.set(prop, value);
       continue;
     }

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

@@ -1,9 +1,8 @@
 /**
- * Fonts slice — sources + stacks. No derived CSS vars owned by this store
- * (the `--font-*` vars are written by `applyFontStacks` in fontLoader, and
- * @font-face rules by `applyFontSources`). We own the *data* (sources +
- * stacks); callers still invoke the DOM-side-effect helpers themselves
- * after mutating.
+ * Fonts slice — sources + stacks. The editor renderer projects both from the
+ * store: stacks become `--font-*` vars and sources become mirrored
+ * <link>/<style> nodes. Callers only mutate data; undo/redo and hydration then
+ * use the exact same reactive path as the initial edit.
  */
 import type { FontSource, FontStack } from '../themeTypes';
 import { store, mutate, persist } from '../../store/editorCore';

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

@@ -0,0 +1,66 @@
+import { liveMovedSinceBake } from '../productionPulse';
+import { openThemeSlug } from '../store/editorConfigStore';
+import { loadThemeFromApi } from '../store/editorStore';
+import { migrateColorsAndTypeFonts } from '../fonts/fontMigration';
+import type { ApplyThemeResult } from './themeService';
+
+const CHANNEL_NAME = 'live-tokens:active-theme:v1';
+export const THEME_APPLIED_EVENT = 'live-tokens:theme-applied';
+
+export interface AppliedThemeDetail {
+  fileName: string;
+  result: ApplyThemeResult;
+}
+
+interface AppliedThemeMessage {
+  type: 'theme-applied';
+  fileName: string;
+  result: ApplyThemeResult;
+}
+
+let channel: BroadcastChannel | null = null;
+
+function isAppliedThemeMessage(value: unknown): value is AppliedThemeMessage {
+  if (!value || typeof value !== 'object') return false;
+  const message = value as Partial<AppliedThemeMessage>;
+  return message.type === 'theme-applied'
+    && typeof message.fileName === 'string'
+    && !!message.result
+    && typeof message.result === 'object'
+    && !!message.result.colorsAndType
+    && typeof message.result.componentConfigs === 'object';
+}
+
+/**
+ * Replace this document's editor state with the complete state returned by
+ * the theme apply endpoint. Each same-origin document owns its own Svelte
+ * store, so writing CSS into another document is not enough: the receiving
+ * editor must hydrate the typed palette and component layers as well.
+ */
+export function hydrateAppliedTheme(fileName: string, result: ApplyThemeResult): void {
+  const colorsAndType = structuredClone(result.colorsAndType);
+  migrateColorsAndTypeFonts(colorsAndType);
+  loadThemeFromApi(colorsAndType, structuredClone(result.componentConfigs));
+  openThemeSlug.set(fileName);
+  liveMovedSinceBake.set(false);
+  if (typeof document !== 'undefined') {
+    document.dispatchEvent(new CustomEvent<AppliedThemeDetail>(THEME_APPLIED_EVENT, {
+      detail: { fileName, result },
+    }));
+  }
+}
+
+/** Install the same-origin theme bridge for this window or iframe. */
+export function init(): void {
+  if (channel || typeof BroadcastChannel === 'undefined') return;
+  channel = new BroadcastChannel(CHANNEL_NAME);
+  channel.addEventListener('message', (event: MessageEvent<unknown>) => {
+    if (!isAppliedThemeMessage(event.data)) return;
+    hydrateAppliedTheme(event.data.fileName, event.data.result);
+  });
+}
+
+/** Notify every already-open editor/host document after the server switches. */
+export function broadcastAppliedTheme(fileName: string, result: ApplyThemeResult): void {
+  channel?.postMessage({ type: 'theme-applied', fileName, result } satisfies AppliedThemeMessage);
+}

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

@@ -1,7 +1,6 @@
 import type { AliasDiskValue, ColorsAndType } from './themeTypes';
 import { openThemeSlug } from '../store/editorConfigStore';
 import { migrateColorsAndTypeFonts } from '../fonts/fontMigration';
-import { applyFontSources, applyFontStacks } from '../fonts/fontLoader';
 import { loadFromFile, seedComponentsFromApi } from '../store/editorStore';
 import { getActiveComponentConfig, type ComponentSummary } from '../components/componentConfigService';
 import { safeFetch } from '../storage/storage';
@@ -33,12 +32,6 @@ export async function initializeTheme(): Promise<void> {
   if (colorsAndType) {
     migrateColorsAndTypeFonts(colorsAndType);
     loadFromFile(colorsAndType);
-    if (colorsAndType.fontSources && colorsAndType.fontSources.length > 0) {
-      applyFontSources(colorsAndType.fontSources);
-    }
-    if (colorsAndType.fontStacks && colorsAndType.fontStacks.length > 0) {
-      applyFontStacks(colorsAndType.fontStacks, colorsAndType.fontSources ?? []);
-    }
     openThemeSlug.set(colorsAndType._fileName || 'default');
   }
 
@@ -48,6 +41,7 @@ export async function initializeTheme(): Promise<void> {
       string,
       { aliases: Record<string, AliasDiskValue>; config?: Record<string, unknown>; schemaVersion?: number }
     > = {};
+    let componentReadFailed = false;
     await Promise.all(
       list.components.map(async (c) => {
         const cfg = await getActiveComponentConfig(c.name);
@@ -57,11 +51,14 @@ export async function initializeTheme(): Promise<void> {
             config: cfg.config,
             schemaVersion: cfg.schemaVersion,
           };
+        } else {
+          componentReadFailed = true;
         }
       }),
     );
-    if (Object.keys(configs).length > 0) {
-      seedComponentsFromApi(configs);
-    }
+    // A successful empty list is authoritative. A partial read is not: avoid
+    // replacing the visible design system with a mixture of active configs
+    // and CSS defaults because one request happened to fail during boot.
+    if (!componentReadFailed) seedComponentsFromApi(configs);
   }
 }

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

@@ -4,6 +4,7 @@ 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';
 
 /**
  * REST client for theme files, the documents of the editor. A theme carries a
@@ -67,8 +68,11 @@ export interface ApplyThemeResult {
  * `themes/_active.json` at it, and returns the resolved state in one payload.
  * Live reads then fall through to the theme's embedded layers.
  * Production is untouched, so trying a look cannot change what the site ships.
- * Clients follow with a full page reload; opening a theme is a "blow up the
- * world" action.
+ * The resolved response hydrates the caller immediately, then broadcasts the
+ * same typed state to every already-open same-origin host/editor document.
+ * Each store renderer projects that state into its own document, so a theme
+ * loaded from either side keeps the controls, aliases, and visible components
+ * on the same design system without a reload.
  */
 export async function applyTheme(fileName: string): Promise<ApplyThemeResult> {
   const res = await fetch(`${API_BASE}/themes/${encodeURIComponent(fileName)}/apply`, {
@@ -78,7 +82,10 @@ export async function applyTheme(fileName: string): Promise<ApplyThemeResult> {
     const err = await res.json().catch(() => ({ error: 'Apply failed' }));
     throw new Error(err.error || 'Apply failed');
   }
-  return res.json();
+  const result = await res.json() as ApplyThemeResult;
+  hydrateAppliedTheme(fileName, result);
+  broadcastAppliedTheme(fileName, result);
+  return result;
 }
 
 export interface AdoptLookResult {

package/src/editor/docs/content/themes-workflow.md

@@ -30,7 +30,8 @@ A theme is a document, and the editor works the way any editor does.
   one slot per part of the look. **Save** captures that buffer into the open
   theme.
 - **The production theme** is the one your site ships, named in
-  `themes/_production.json`. Only **Adopt** changes it.
+  `themes/_production.json`. **Adopt** changes it; saving a preset in the Theme
+  Picker performs that Adopt for you.
 
 Absence is the answer for anything untouched: a buffer exists only where the
 live look diverges from the active theme, so a newly opened theme has none.
@@ -43,9 +44,11 @@ In the Theme panel:
   go in as part of it, so there is nothing to save first.
 - **Save As** names a new theme. Use it for your first save and for forking.
 
-Component edits are the exception. Each component editor holds its own unsaved
-state, which this panel cannot write, so save a component in its editor before
-capturing it. The panel says how many are waiting.
+Component editors keep their own unsaved state. If one or more components are
+waiting when you use **Save**, **Save As**, or **Adopt**, the Theme panel offers
+to save all of them before continuing. You can accept once instead of visiting
+each component, or cancel to review them individually. A component editor's
+**Save As** creates a reusable component preset.
 
 Names are tidied to lowercase with hyphens, so "My Brand!" becomes `my-brand`,
 and a leading underscore is dropped: those names are reserved for the buffer.
@@ -54,13 +57,13 @@ to it, and the editor never overwrites it, so start your own with **Save As**.
 
 ## Switching
 
-**Load** lists your saved themes and the seven example looks. Picking one shows
-it on the page as a preview with nothing written to disk, so you can try each
-look and compare. **Save** in that window opens the previewed theme: the active
-pointer changes, the buffers clear, components it does not carry fall through
-to their defaults, and the editor works on it from then on. **Cancel** returns
-you to where you were.
-Trying a look never changes what your site ships.
+**Load**—or clicking the active theme's name—opens the Theme Picker. Picking a
+theme shows it on the page as a preview with nothing written to disk, so you can
+try each look and compare. **Save** in that window opens and adopts the previewed
+theme in one step: the active pointer changes, the buffers clear, components it
+does not carry fall through to their defaults, the editor works on it, and
+production ships it. **Cancel** returns you to where you were. Previewing alone
+never changes what your site ships.
 
 **Colors and type only. Keep my shapes.** narrows the load to the palette and
 the fonts: your component settings stay as they are and the theme you have open

package/src/editor/docs/content/where-themes-live.md

@@ -34,8 +34,8 @@ deleting anything else never breaks it.
 
 - **Editing** changes the page through CSS variables. The editor keeps your
   edits in the browser as you work and writes them to the `_working.json`
-  buffers when you save a component. A buffer exists only where the live layer
-  differs from the active theme's saved layer, so a fresh project has none.
+  buffers when you save a component. When the Theme panel finds several dirty
+  components, **Save all** writes those buffers together.
 - **Save** captures the buffers into the open theme's file. That file is the
   durable copy of your look; matching buffers are then removed.
 - **Load** clears the buffers and points `themes/_active.json` at the theme you