@motion-proto/live-tokens 0.47.0 → 0.48.0

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

@@ -1,102 +1,242 @@
-import { tick } from 'svelte';
-import type { Theme, ThemeMeta } from './themeTypes';
-import type { EditorState } from '../store/editorTypes';
-import {
-  versionedFileResource,
-  sanitizeFileName as sanitizeFileNameImpl,
-} from '../storage/files/versionedFileResourceClient';
+import type { Theme, ThemeMeta, ThemeBundle, ColorsAndType, ComponentConfig } from './themeTypes';
+import { versionedFileResource } from '../storage/files/versionedFileResourceClient';
 import { API_BASE } from '../storage/apiBase';
-import { loadFromFile as loadEditorState, toTheme, markSaved } from '../store/editorStore';
-import { activeFileName } from '../store/editorConfigStore';
-import { applyFontSources, applyFontStacks } from '../fonts/fontLoader';
-import { migrateThemeFonts } from '../fonts/fontMigration';
-
-// ── API helpers ──────────────────────────────────────────────
-//
-// All theme CRUD goes through `versionedFileResource(`${API_BASE}/themes`)` —
-// shared with `componentConfigService`'s per-component clients. Theme-specific
-// response shapes (ThemeMeta list payload, ProductionInfo) are layered on top
-// via the generic type parameters.
-
-export interface ProductionInfo {
-  fileName: string;
-  name: string;
-  updatedAt: string;
-  cssVariables: Record<string, string>;
-}
+import { liveMovedSinceBake } from '../productionPulse';
+import { listComponents, getActiveComponentConfig } from '../components/componentConfigService';
+import { getActiveColorsAndType } from './colorsAndTypeService';
+
+/**
+ * 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
+ * published (`themes/_production.json`); the live look is the open theme plus
+ * whatever the `_working` buffers hold over it.
+ *
+ * `default` is the protected baseline — cannot be overwritten or deleted, and
+ * Adopt returns 409 ACTIVE_IS_PROTECTED while it is open.
+ */
 
-const themeResource = versionedFileResource<Theme, ThemeMeta, ProductionInfo>({
+const themesResource = versionedFileResource<Theme, ThemeMeta>({
   baseUrl: `${API_BASE}/themes`,
 });
 
-export async function listThemes(): Promise<ThemeMeta[]> {
-  const data = await themeResource.list();
+export const listThemes = async (): Promise<ThemeMeta[]> => {
+  const data = await themesResource.list();
   return data.files;
-}
+};
 
-export const loadTheme = (fileName: string): Promise<Theme> => themeResource.load(fileName);
+export const loadTheme = (fileName: string): Promise<Theme> =>
+  themesResource.load(fileName);
 export const saveTheme = (fileName: string, data: Theme): Promise<void> =>
-  themeResource.save(fileName, data);
-export const deleteTheme = (fileName: string): Promise<void> => themeResource.remove(fileName);
+  themesResource.save(fileName, data);
+export const deleteTheme = (fileName: string): Promise<void> =>
+  themesResource.remove(fileName);
+export const getActiveTheme = (): Promise<Theme | null> => themesResource.getActive();
+export const setActiveTheme = (fileName: string): Promise<void> =>
+  themesResource.setActive(fileName);
 
-export async function getActiveTheme(): Promise<Theme | null> {
-  return themeResource.getActive();
+/** The published theme, served whole so the client can tell what production
+ *  runs from the document itself. */
+export async function getProductionTheme(): Promise<Theme> {
+  const res = await fetch(`${API_BASE}/themes/production`);
+  if (!res.ok) throw new Error('Failed to read the production theme');
+  return res.json();
 }
 
-export const setActiveFile = (fileName: string): Promise<void> => themeResource.setActive(fileName);
+/** Step past the theme names already on disk rather than clobbering one. */
+export function freshName(base: string, taken: Set<string>): string {
+  if (!taken.has(base)) return base;
+  for (let n = 1; n < 1000; n++) {
+    const candidate = `${base}_${String(n).padStart(2, '0')}`;
+    if (!taken.has(candidate)) return candidate;
+  }
+  return `${base}_${Date.now()}`;
+}
 
-// ── Production API helpers ─────────────────────────────────
+export interface ApplyThemeResult {
+  ok: boolean;
+  theme: Theme;
+  colorsAndType: ColorsAndType;
+  componentConfigs: Record<string, ComponentConfig>;
+  /** Components the theme carries data for that this install doesn't have. */
+  skippedComponents: string[];
+}
 
-export const getProductionInfo = (): Promise<ProductionInfo> => themeResource.getProductionInfo();
+/**
+ * Open a theme: the server writes its embedded copies into the `_working`
+ * buffers, clears the buffer of every component it does not carry, points
+ * `themes/_active.json` at it and returns the resolved state in one payload.
+ * 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.
+ */
+export async function applyTheme(fileName: string): Promise<ApplyThemeResult> {
+  const res = await fetch(`${API_BASE}/themes/${encodeURIComponent(fileName)}/apply`, {
+    method: 'PUT',
+  });
+  if (!res.ok) {
+    const err = await res.json().catch(() => ({ error: 'Apply failed' }));
+    throw new Error(err.error || 'Apply failed');
+  }
+  return res.json();
+}
 
-export async function setProductionFile(
-  fileName: string,
-): Promise<{ ok: boolean; fileName: string; name: string }> {
-  const data = await themeResource.setProduction(fileName);
-  return { ok: data.ok, fileName: data.fileName, name: data.name };
+export interface AdoptLookResult {
+  ok: boolean;
+  /** The theme production now ships. */
+  productionTheme: { fileName: string; name: string; updatedAt: string };
+}
+
+/**
+ * Publish the open theme: `themes/_production.json` names it and
+ * `tokens.generated.css` plus `fonts.css` are rebaked from its embedded
+ * content. What is SAVED ships, so the caller saves the theme first; a buffer
+ * the server has not been handed is invisible from here.
+ *
+ * Answers 409 `ACTIVE_IS_PROTECTED` while the Default theme is open, which the
+ * caller recovers from by forking it under a name of the user's own.
+ */
+export async function adoptLook(): Promise<AdoptLookResult> {
+  const res = await fetch(`${API_BASE}/production`, { method: 'PUT' });
+  if (!res.ok) {
+    const body = await res.json().catch(() => ({}));
+    const err = new Error(body.error || 'Adopt failed') as Error & {
+      status?: number;
+      code?: string;
+    };
+    err.status = res.status;
+    if (body.code) err.code = body.code;
+    throw err;
+  }
+  liveMovedSinceBake.set(false);
+  return res.json();
 }
 
-/** Sanitize a display name to a safe file name. Re-exported from the shared
- * `files/versionedFileResource` so the dev-server plugin can import the
- * canonical pure helper without depending on this module's CSS imports. */
-export const sanitizeFileName = sanitizeFileNameImpl;
-
-// ── Theme save/load orchestration ──────────────────────────
-//
-// `persistTheme` and `hydrateTheme` are the canonical entry points for
-// round-tripping editor state to disk. Callers (e.g. `EditorShell`) need
-// only handle UI-level concerns (status flashing, error chrome) and
-// delegate the actual orchestration here.
-
-/** Snapshot the editor state to disk under `fileName`, mark the file active,
- *  and clear the dirty flag. The caller is responsible for surfacing
- *  saving / saved / error UI states around this call. */
-export async function persistTheme(
-  state: EditorState,
+/** `_fileName` and `_source` mark which document and which layer a read door
+ *  answered from; neither is part of the content we send back. */
+function withoutLiveMarkers<T extends { _fileName?: string; _source?: unknown }>(value: T): T {
+  const { _fileName, _source, ...rest } = value;
+  return rest as T;
+}
+
+/**
+ * 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.
+ *
+ * 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
+ * way out of `GET /colors-and-type/active`, which matters: the server trusts an
+ * already-embedded copy and runs no migrations over it on write.
+ */
+async function captureLook(): Promise<Pick<Theme, 'colorsAndType' | 'componentConfigs'>> {
+  const liveColorsAndType = await getActiveColorsAndType();
+  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 componentConfigs: Record<string, ComponentConfig> = {};
+  overridden.forEach((c, i) => {
+    const config = configs[i];
+    if (config) componentConfigs[c.name] = withoutLiveMarkers(config);
+  });
+  return { colorsAndType: withoutLiveMarkers(liveColorsAndType), componentConfigs };
+}
+
+/**
+ * Capture the current look into a new theme file and open it. Used by the
+ * theme panel's Save As action and by the fork-then-Adopt flow the protected
+ * Default theme forces.
+ */
+export async function saveAsTheme(
   fileName: string,
   displayName: string,
 ): Promise<void> {
-  await tick();
-  const theme = toTheme(state, { name: displayName });
-  await saveTheme(fileName, theme);
-  await setActiveFile(fileName);
-  activeFileName.set(fileName);
-  markSaved();
+  const look = await captureLook();
+  const now = new Date().toISOString();
+  await saveTheme(fileName, {
+    name: displayName,
+    createdAt: now,
+    updatedAt: now,
+    schemaVersion: 3,
+    ...look,
+  });
+  liveMovedSinceBake.set(true);
+  await setActiveTheme(fileName);
+}
+
+/**
+ * Re-capture the current look into the open theme file. Used by the theme
+ * panel's Save action and by both Adopt paths, which publish what is saved.
+ * The server rejects with 403 while the protected `default` theme is open.
+ */
+export async function saveActiveTheme(displayName?: string): Promise<void> {
+  const active = await getActiveTheme();
+  if (!active || !active._fileName) {
+    throw new Error('No active theme');
+  }
+  const look = await captureLook();
+  await saveTheme(active._fileName, {
+    name: displayName ?? active.name,
+    createdAt: active.createdAt,
+    updatedAt: new Date().toISOString(),
+    schemaVersion: 3,
+    ...look,
+  });
+  liveMovedSinceBake.set(true);
+}
+
+export interface ImportThemeResult {
+  ok: boolean;
+  /** Final theme filename (may be renamed if it collided with an existing one). */
+  theme: string;
+  /** Keyed `theme:<orig>` → final name. */
+  renames: Record<string, string>;
+  /** Refs a v1 bundle failed to carry, as `colors-and-type:<name>` /
+   *  `<comp>/<name>`. Each fell back to the default. */
+  dropped: string[];
 }
 
-/** Load a theme file into the editor state and re-apply font side-effects
- *  (@font-face rules + `--font-*` CSS vars on :root). */
-export async function hydrateTheme(fileName: string): Promise<void> {
-  const theme = await loadTheme(fileName);
-  migrateThemeFonts(theme);
-  loadEditorState(theme);
-  // 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 (theme.fontSources && theme.fontSources.length > 0) {
-    applyFontSources(theme.fontSources);
+/**
+ * Fetch the theme as a `ThemeBundle` and trigger a browser download.
+ * Hidden-anchor trick — no infrastructure beyond the existing GET
+ * `/api/themes/:name/export` endpoint.
+ */
+export async function exportTheme(fileName: string): Promise<void> {
+  const res = await fetch(`${API_BASE}/themes/${encodeURIComponent(fileName)}/export`);
+  if (!res.ok) {
+    const err = await res.json().catch(() => ({ error: 'Export failed' }));
+    throw new Error(err.error || 'Export failed');
   }
-  if (theme.fontStacks && theme.fontStacks.length > 0) {
-    applyFontStacks(theme.fontStacks, theme.fontSources ?? []);
+  const blob = await res.blob();
+  const url = URL.createObjectURL(blob);
+  try {
+    const a = document.createElement('a');
+    a.href = url;
+    a.download = `${fileName}.bundle.json`;
+    document.body.appendChild(a);
+    a.click();
+    a.remove();
+  } finally {
+    URL.revokeObjectURL(url);
+  }
+}
+
+/**
+ * POST a `ThemeBundle` to the import endpoint. The server writes one
+ * theme file (renaming on collision) and returns its final name; nothing is
+ * materialised until Apply. v1 bundles from older installs are accepted too.
+ */
+export async function importTheme(bundle: ThemeBundle): Promise<ImportThemeResult> {
+  const res = await fetch(`${API_BASE}/themes/import`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(bundle),
+  });
+  if (!res.ok) {
+    const err = await res.json().catch(() => ({ error: 'Import failed' }));
+    throw new Error(err.error || 'Import failed');
   }
+  return res.json();
 }

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

@@ -34,8 +34,19 @@ export interface PaletteConfig {
    * `displacedS` remember the y of a pre-existing anchor (endpoint or
    * user-authored) the placement overwrote at that x, so moving the
    * placement or toggling off restores it instead of deleting it.
+   * `priorLightnessEndpoints` / `priorSaturationEndpoints` remember the two
+   * endpoints exactly as they stood before the curve's first-ever placement
+   * (a smoothed reshape, not algebraically invertible the way a later
+   * scaled-handle re-placement is), so a clear can still restore the true
+   * original regardless of how many times the anchor has since moved.
    */
-  anchorPlacement?: { step: number; displacedL?: number; displacedS?: number };
+  anchorPlacement?: {
+    step: number;
+    displacedL?: number;
+    displacedS?: number;
+    priorLightnessEndpoints?: [CurveAnchor, CurveAnchor];
+    priorSaturationEndpoints?: [CurveAnchor, CurveAnchor];
+  };
   /**
    * Set to true by importers when they overlay `cssVariables[--color-{ns}-*]`
    * without owning the typed-state curves. The storage-layer reconciler uses
@@ -83,7 +94,31 @@ export interface FontStack {
   slots: FontStackSlot[];
 }
 
-export interface Theme {
+/** On-disk shape of one `--gradient-N` library token. Structural mirror of the
+ *  store's `GradientToken` (like `AliasDiskValue`'s inline gradient shape) so
+ *  the file schema stays independent of store types. The rendered strings in
+ *  `cssVariables` are a projection of these for production CSS; this field is
+ *  the editable basis. */
+export interface GradientDiskToken {
+  variable: string;
+  type: 'linear' | 'radial' | 'solid' | 'none';
+  angle: number;
+  radius?: number;
+  centerX?: number;
+  aspectX?: number;
+  aspectY?: number;
+  stops: { position: number; color: string; opacity?: number }[];
+}
+
+/**
+ * Where a live read resolved from: the unsaved `_working` buffer, the open
+ * theme's embedded copy, or the shipped default. It says which layer answered,
+ * never whether the content was edited — applying a theme fills the buffer for
+ * every layer it carries.
+ */
+export type LiveSource = 'working' | 'theme' | 'default';
+
+export interface ColorsAndType {
   name: string;
   createdAt: string;
   updatedAt: string;
@@ -91,14 +126,19 @@ export interface Theme {
   cssVariables: Record<string, string>;
   fontSources?: FontSource[];
   fontStacks?: FontStack[];
+  /** Absent on files saved before gradients round-tripped; the loader keeps
+   *  the stock defaults then, which match what those files rendered. */
+  gradients?: GradientDiskToken[];
   /** Four fixed harmony axes, each owning a hue with an optional bound family. */
   harmonyAxes?: HarmonyAxis[];
   /**
-   * Server-attached file-name marker for round-tripping the file identity
-   * back to the client. Set by `themeFileApi`'s GET handlers; read by
-   * `themeInit` to seed `activeFileName`. Optional and not persisted to disk.
+   * Server-attached marker naming the open theme — the document this content
+   * belongs to, not a colors-and-type file. Set by `themeFileApi`'s GET
+   * handlers; read by `themeInit` to seed `openThemeSlug`. Not persisted.
    */
   _fileName?: string;
+  /** Server-attached marker: which of the three live layers answered. */
+  _source?: LiveSource;
   /**
    * Migration stamp. Absent on legacy files, treated as 0; the loader runs
    * any registered theme migrations whose `fromVersion >= file.schemaVersion`.
@@ -108,11 +148,13 @@ export interface Theme {
   schemaVersion?: number;
 }
 
-export interface ThemeMeta {
+export interface ColorsAndTypeMeta {
   name: string;
   fileName: string;
   updatedAt: string;
-  isActive: boolean;
+  /** The file is served from the installed package and no local copy shadows
+   *  it: one of the shipped presets or the default, not a file the user made. */
+  isPackage: boolean;
 }
 
 /** On-disk shape of a single alias entry. Plain strings carry the bulk of
@@ -131,12 +173,14 @@ export interface ComponentConfig {
   aliases: Record<string, AliasDiskValue>;
   config?: Record<string, unknown>;
   /**
-   * Server-attached file-name marker. Same role as `Theme._fileName`. Set by
-   * the component-configs GET handlers; not persisted to disk.
+   * Server-attached marker. Same role as `ColorsAndType._fileName`: the open
+   * theme, not a config file. Set by the component-configs GET handlers.
    */
   _fileName?: string;
+  /** Server-attached marker: which of the three live layers answered. */
+  _source?: LiveSource;
   /**
-   * Migration stamp. Absent on legacy files, treated as 0. See `Theme.schemaVersion`.
+   * Migration stamp. Absent on legacy files, treated as 0. See `ColorsAndType.schemaVersion`.
    */
   schemaVersion?: number;
 }
@@ -145,71 +189,70 @@ export interface ComponentConfigMeta {
   name: string;
   fileName: string;
   updatedAt: string;
-  isActive: boolean;
-  isProduction: boolean;
 }
 
 /**
- * Manifest that captures an entire site state — the active theme plus the
- * active config for every component. Loading a manifest flips the relevant
- * `_active.json` pointers; the underlying theme + component-config files stay
- * the source of truth, so editing them flows through any manifest that
- * references them. The currently-active manifest is the live snapshot: theme
- * and component Adopts auto-patch its refs on the server.
+ * A saved look, encapsulated: the colors and type plus a config for every
+ * component that sits off its default, all carried by value. Themes are the
+ * documents of the editor. Applying one opens it: its embedded copies land in
+ * the reserved `_working` buffers and `themes/_active.json` names it. Saving
+ * captures the live buffers back into it; Adopt publishes it, and only then is
+ * `tokens.generated.css` rebaked.
  */
-export interface Manifest {
+export interface Theme {
   name: string;
   createdAt: string;
   updatedAt: string;
-  /** File basename (no `.json`) of the theme this manifest pins. */
-  theme: string;
-  /** Map of componentId → config file basename. Components omitted here fall
-   *  back to "default" at apply time. */
-  componentConfigs: Record<string, string>;
-  /** Server-attached file-name marker. Same role as `Theme._fileName`. */
+  /** Migration stamp. 1 was the pointer form (colors-and-type + config
+   *  basenames); 2 encapsulated it under a `theme` key; 3 spells that key
+   *  `colorsAndType`. The server rewrites older files at boot. */
+  schemaVersion: 3;
+  /** Full colors-and-type content. */
+  colorsAndType: ColorsAndType;
+  /** Component id → its config. Delta encoding: a component absent here is on
+   *  its default. Defaults are never inlined — the local `default.json` derived
+   *  from the component source is canonical, and a frozen copy would drift. */
+  componentConfigs: Record<string, ComponentConfig>;
+  /** Server-attached file-name marker. Same role as `ColorsAndType._fileName`. */
   _fileName?: string;
 }
 
 /**
- * Transport artifact for sharing a manifest with someone else. Self-contained:
- * the bundle inlines the referenced theme and every non-default component
- * config so the receiver doesn't need anything else on disk to apply it.
+ * Transport envelope for sharing a theme. The theme already carries
+ * everything needed to apply it, so the envelope adds only provenance.
  *
- * Bundles are *not* stored under `manifests/` — they're transient downloads /
- * uploads. Local manifests stay lightweight pointer files; bundles are the
- * import/export envelope. See temp/manifest-robustness-plan.md §11.
- *
- * `componentConfigs` is keyed by `${component}/${configName}` so a single map
- * carries multiple components. Entries whose manifest value is `"default"`
- * are deliberately omitted — the receiver's local `default.json` is the
- * live-tokens package's canonical default, and shipping the sender's default
- * would risk version-divergence with no clean conflict story.
+ * Bundles are *not* stored under `themes/` — they're transient downloads /
+ * uploads; import writes the enclosed theme as a single file.
  */
-export interface ManifestBundle {
-  /** Discriminator for safe identification of bundle JSON files. */
-  kind: 'manifest-bundle';
-  /** Bumps when the bundle envelope shape changes. Start at 1. */
-  schemaVersion: 1;
+export interface ThemeBundle {
+  /** Discriminator for safe identification of bundle JSON files. Paired with
+   *  the version below: import accepts this kind only at v3, and the
+   *  `manifest-bundle` every release through 0.47.1 wrote only at v1. */
+  kind: 'theme-bundle';
+  /** Tracks the enclosed theme's schema. Import still accepts 1, where the
+   *  envelope carried a pointer theme plus separately inlined colors and type
+   *  and `${component}/${configName}`-keyed configs. */
+  schemaVersion: 3;
   /** Sender's `@motion-proto/live-tokens` package version. Receiver can
    *  compare to its own to warn about compatibility drift. */
   liveTokensVersion: string;
   /** ISO timestamp of when the bundle was exported. */
   exportedAt: string;
-  /** Full pointer-form manifest (same shape as on-disk manifest files). */
-  manifest: Manifest;
-  /** Full content of the theme that `manifest.theme` references. */
-  theme: Theme;
-  /** Full content of each non-default component config referenced by
-   *  `manifest.componentConfigs`, keyed by `${component}/${configName}`. */
-  componentConfigs: Record<string, ComponentConfig>;
+  /** Keeps the `manifest` spelling: a v1 bundle's `theme` is the separately
+   *  inlined colors and type, which import still reads, so the envelope cannot
+   *  take that name without meaning two things at once. */
+  manifest: Theme;
 }
 
-export interface ManifestMeta {
+export interface ThemeMeta {
   name: string;
   fileName: string;
   updatedAt: string;
   isActive: boolean;
+  /** The theme `tokens.generated.css` was last baked from. */
+  isProduction: boolean;
   /** `true` only for `default` — the protected baseline. Cannot be written
-   *  to or deleted, and theme/component Adopts cannot patch into it. */
+   *  to or deleted, and colors-and-type / component Adopts cannot patch into
+   *  it. */
   isProtected: boolean;
 }

package/src/editor/docs/Docs.svelte

@@ -99,6 +99,7 @@
         { path: 'getting-started',     title: 'Getting started' },
         { path: 'editing-tokens',      title: 'Editing tokens' },
         { path: 'themes-workflow',     title: 'Themes' },
+        { path: 'where-themes-live',   title: 'Where themes live' },
         { path: 'creating-components', title: 'Creating components' },
       ],
     },

package/src/editor/docs/chapters.ts

@@ -14,6 +14,7 @@ export const chapters: Chapter[] = [
   { id: 'getting-started',     title: 'Getting started' },
   { id: 'editing-tokens',      title: 'Editing tokens' },
   { id: 'themes-workflow',     title: 'Themes' },
+  { id: 'where-themes-live',   title: 'Where themes live' },
   { id: 'creating-components', title: 'Creating components' },
 ];
 

package/src/editor/docs/content/01-overview.md

@@ -1,7 +1,7 @@
 # Overview
 
 Live Tokens is a design system for building Svelte microsites quickly. You
-style your site by editing tokens and components in a live editor. When it looks right, you save the manifest and ship it.
+style your site by editing tokens and components in a live editor. When it looks right, you save the theme and ship it.
 
 ## How it works
 

package/src/editor/docs/content/editing-tokens.md

@@ -65,10 +65,10 @@ live.
 ## Saving
 
 The editor saves to your browser continuously, so work survives a reload
-mid-edit. **Save** is a separate step: it writes a named theme file under
-`src/live-tokens/data/themes/`.
+mid-edit. Writing a file is a separate step: the **Theme** panel at the foot of
+the sidebar has **Save**, **Save As**, and **Load**, and each theme is one JSON
+file under `src/live-tokens/data/themes/`.
 
-The header gives you undo/redo (`Cmd/Ctrl+Z`, `Cmd/Ctrl+Shift+Z`) and a file
-menu for New, Save, Save as, Switch, and Delete. You can keep many themes side
-by side; one is active at a time. See [Themes](themes-workflow.md) for the full
-lifecycle.
+The header gives you undo/redo (`Cmd/Ctrl+Z`, `Cmd/Ctrl+Shift+Z`). You can keep
+many themes side by side; one is open at a time, and only **Adopt** publishes
+one. See [Themes](themes-workflow.md) for the full lifecycle.

package/src/editor/docs/content/getting-started.md

@@ -39,10 +39,10 @@ version upgrades never touch your styles. The package code stays in
    the page.
 3. Open **Palettes**, pick **Brand**, and change the base hex. The page
    repaints as you type.
-4. Open the file menu and choose **Save as**. A theme appears as JSON under
-   `src/live-tokens/data/themes/`.
-5. Reload. Your saved theme is the active theme, so the page returns as you
-   left it.
+4. In the **Theme** panel at the foot of the sidebar, choose **Save As**. Your
+   theme appears as JSON under `src/live-tokens/data/themes/`.
+5. Reload. The editor reopens on your theme, so the page returns as you left
+   it.
 
 ## What you just changed
 
@@ -51,9 +51,11 @@ properties through `var(--...)`. There is no token build step and no
 preprocessor rewriting your code: the page renders against plain CSS variables
 the editor swaps live.
 
-To ship, promote a theme to production in the editor. That bakes the theme's
-variables into `src/live-tokens/data/tokens.generated.css`, which your build
-bundles alongside `tokens.css`. The editor itself never reaches production.
+To ship, click **Adopt** in the Theme panel. That saves the open theme and bakes
+it into `src/live-tokens/data/tokens.generated.css`, which your build bundles
+alongside `tokens.css`. Adopt is the only action that changes what your site
+ships, so try any look you like first. The editor itself never reaches
+production.
 
 Already have a Svelte 5 + Vite app? The
 [README](https://github.com/motionproto/live-tokens#readme) covers installing