@motion-proto/live-tokens 0.49.1 → 0.52.1

package/dist-plugin/tokensCssMigrations/index.d.ts

@@ -52,6 +52,8 @@ interface TokensCssMigration {
  */
 /** Names declared as custom properties (`--x: …;`) anywhere in the source. */
 declare function collectDefinedTokens(css: string): Set<string>;
+/** Declared name → value, last declaration winning (as the cascade would). */
+declare function collectTokenValues(css: string): Map<string, string>;
 /** Names referenced via `var(--x)` anywhere in the source. */
 declare function collectReferencedTokens(css: string): Set<string>;
 interface ScaleEntry {
@@ -123,16 +125,25 @@ interface ContractViolation {
     id: string;
     /** Token names the migration removed or renamed away despite declaring `additive`. */
     removed: string[];
+    /** Token names whose value the migration rewrote despite declaring `additive`. */
+    changed: string[];
 }
 /**
- * Guardrail for the token-as-API contract: an `additive` migration must never
- * remove or rename a token. We verify behaviorally rather than trusting the
- * label — apply each additive migration to the package's own canonical
- * `tokens.css` (which defines the full current vocabulary) and flag any token
- * that disappears. A rename surfaces as the removal of its old name, so it is
- * caught too. This catches the dangerous direction: a breaking change shipped as
- * a backward-compatible one. (Over-labeling a no-op as `breaking` is harmless
- * and not checked.)
+ * Guardrail for the token-as-API contract: an `additive` migration must only
+ * ever insert new names — it must never remove or rename a token, and never
+ * rewrite the value of one a consumer already references. We verify
+ * behaviorally rather than trusting the label: apply each additive migration to
+ * the package's own canonical `tokens.css` (which defines the full current
+ * vocabulary) and flag any token that disappears or changes value. A rename
+ * surfaces as the removal of its old name, so it is caught too.
+ *
+ * The value half is what makes a value-rewriting migration (hex → `oklch()`)
+ * impossible to mislabel: it renames nothing, so a name-only guard would wave
+ * it through as additive and the dev plugin would auto-apply a breaking change
+ * to a consumer's vendored file.
+ *
+ * This catches the dangerous direction only. (Over-labeling a no-op as
+ * `breaking` is harmless and not checked.)
  */
 declare function findContractViolations(canonicalCss: string): ContractViolation[];
 type SemverBump = 'major' | 'minor' | 'patch' | 'none';
@@ -183,4 +194,4 @@ interface ValidateInput {
  */
 declare function validateTokensCss(input: ValidateInput): MissingToken[];
 
-export { type BreakingGateResult, type ComponentSource, type ContractViolation, type MissingToken, type RunResult, type SemverBump, TOKENS_CSS_MIGRATIONS, type TokensCssMigration, type ValidateInput, collectDefinedTokens, collectReferencedTokens, enforceBreakingRequiresMajor, ensureScale, findContractViolations, removeToken, removeTokensMatching, renameToken, runAdditiveTokensCssMigrations, runTokensCssMigrations, semverBumpType, validateTokensCss };
+export { type BreakingGateResult, type ComponentSource, type ContractViolation, type MissingToken, type RunResult, type SemverBump, TOKENS_CSS_MIGRATIONS, type TokensCssMigration, type ValidateInput, collectDefinedTokens, collectReferencedTokens, collectTokenValues, enforceBreakingRequiresMajor, ensureScale, findContractViolations, removeToken, removeTokensMatching, renameToken, runAdditiveTokensCssMigrations, runTokensCssMigrations, semverBumpType, validateTokensCss };

package/dist-plugin/tokensCssMigrations/index.js

@@ -2,6 +2,7 @@ import {
   TOKENS_CSS_MIGRATIONS,
   collectDefinedTokens,
   collectReferencedTokens,
+  collectTokenValues,
   enforceBreakingRequiresMajor,
   ensureScale,
   findContractViolations,
@@ -12,7 +13,8 @@ import {
   runTokensCssMigrations,
   semverBumpType,
   validateTokensCss
-} from "../chunk-44RSTAII.js";
+} from "../chunk-TKZBVIW5.js";
+import "../chunk-YR6GPXW2.js";
 import {
   readLiveTokensConfig
 } from "../chunk-D3ZVKOR4.js";
@@ -20,6 +22,7 @@ export {
   TOKENS_CSS_MIGRATIONS,
   collectDefinedTokens,
   collectReferencedTokens,
+  collectTokenValues,
   enforceBreakingRequiresMajor,
   ensureScale,
   findContractViolations,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@motion-proto/live-tokens",
-  "version": "0.49.1",
+  "version": "0.52.1",
   "type": "module",
   "description": "Design token editor with live CSS variable editing. Svelte 5 + Vite 8.",
   "keywords": [
@@ -110,6 +110,12 @@
     "check": "svelte-check --tsconfig ./tsconfig.json",
     "test": "vitest run",
     "test:watch": "vitest",
+    "test:e2e": "npm run test:e2e:contract && npm run test:e2e:stateful",
+    "test:e2e:contract": "playwright test tests/e2e/component-render-contract.spec.ts tests/e2e/component-alias-contract.spec.ts --workers=4",
+    "test:e2e:stateful": "playwright test tests/e2e/live-editing.spec.ts tests/e2e/theme-workflow.spec.ts --workers=1",
+    "test:e2e:components": "playwright test tests/e2e/component-render-contract.spec.ts",
+    "test:e2e:ui": "playwright test --ui",
+    "prepare:e2e": "node scripts/prepare-playwright-data.mjs",
     "build:plugin": "tsup",
     "build:lib": "npm run build:plugin",
     "deploy:local": "bash scripts/deploy-local.sh",
@@ -136,6 +142,7 @@
     "vite": "^8"
   },
   "devDependencies": {
+    "@playwright/test": "^1.62.1",
     "@sveltejs/vite-plugin-svelte": "^7.1.2",
     "@types/node": "^25.9.1",
     "happy-dom": "^20.9.0",

package/src/editor/bootstrap.ts

@@ -19,6 +19,7 @@ import * as cssVarSync from './core/cssVarSync';
 import * as router from './core/routing/router';
 import * as columnsOverlay from './overlay/columnsOverlay';
 import * as editorStore from './core/store/editorStore';
+import * as themeDocumentSync from './core/themes/themeDocumentSync';
 import { initializeTheme } from './core/themes/themeInit';
 import { registerComponent, type RegisterComponentEntry } from './component-editor/registry';
 
@@ -38,6 +39,7 @@ export async function bootLiveTokens(
   editorStore.init();
 
   if (import.meta.env.DEV) {
+    themeDocumentSync.init();
     if (opts.components) {
       for (const entry of opts.components) {
         registerComponent(entry);

package/src/editor/component-editor/ButtonEditor.svelte

@@ -165,7 +165,7 @@
           {/if}
         {/snippet}
         {#snippet children({ activeState })}
-          {@const forceClass = activeState === 'hover' ? 'force-hover' : ''}
+          {@const forceClass = activeState === 'hover' ? 'force-hover' : activeState === 'active' ? 'force-active' : ''}
           {@const isDisabled = activeState === 'disabled'}
           <div class="button-showcase-grid">
             <div class="button-showcase-item">

package/src/editor/component-editor/CardEditor.svelte

@@ -144,7 +144,10 @@
   >
     {#snippet stateActions(stateName)}
       {#if stateName === 'hover'}
-        <div class="hover-control">
+        <div
+          class="hover-control"
+          data-token-variables="--card-hover-border-active --card-hover-shadow-active"
+        >
           <label class="hover-enable">
             <input type="checkbox" checked={hoverEnabled} onchange={(e) => setHoverEnabled(e.currentTarget.checked)} />
             <span>Use hover</span>
@@ -159,7 +162,7 @@
     {#snippet children({ activeState })}
       {@const previewClass = activeState === 'hover' ? 'force-hover' : ''}
       <div class="card-demo">
-        <Card title="Card title" class={previewClass}>
+        <Card title="Card title" icon="fas fa-star" class={previewClass}>
           <div class="content-placeholder">Content Placeholder</div>
         </Card>
       </div>

package/src/editor/component-editor/IconButtonEditor.svelte

@@ -140,7 +140,7 @@
         previewActions={sizeAction}
       >
         {#snippet children({ activeState })}
-          {@const forceClass = activeState === 'hover' ? 'force-hover' : ''}
+          {@const forceClass = activeState === 'hover' ? 'force-hover' : activeState === 'active' ? 'force-active' : ''}
           {@const isDisabled = activeState === 'disabled'}
           <IconButton variant={v} icon={previewIcons[v]} ariaLabel={`${v} action`} disabled={isDisabled} class={forceClass} />
         {/snippet}

package/src/editor/component-editor/ImageEditor.svelte

@@ -78,7 +78,7 @@
         <span>Overflow scaling (mask zoom to frame)</span>
       </label>
     {/snippet}
-    <Image src={demoImageUrl} alt="Demo" variant="banner" zoom={useZoom ? undefined : false} {overflowScaling} />
+    <Image src={demoImageUrl} alt="Demo" variant="banner" zoom={useZoom ? undefined : false} {overflowScaling} forceHover={useZoom} />
     <p class="zoom-help">
       Use zoom on hover: every image scales on hover (a page can still force it per image with the
       <code>zoom</code> prop). Overflow scaling on (default): the content zooms inside the fixed frame,

package/src/editor/component-editor/NotificationEditor.svelte

@@ -87,12 +87,14 @@
   let dismissible = $state(false);
   let rightOption: ButtonVariantOption = $state('none');
   let leftOption: ButtonVariantOption = $state('none');
+  let headerAction = $state(false);
   let actions = $derived(((): NotificationActions => {
     const a: NotificationActions = {};
     const right = toVariant(rightOption);
     const left = toVariant(leftOption);
     if (right) a.right = { label: 'Confirm', variant: right, onClick: () => {} };
     if (left) a.left = { label: 'Cancel', variant: left, onClick: () => {} };
+    if (headerAction) a.header = { label: 'Action', onClick: () => {} };
     return a;
   })());
 </script>
@@ -112,6 +114,10 @@
           <input type="checkbox" bind:checked={dismissible} />
           <span>Dismissible</span>
         </label>
+        <label class="toolbar-check">
+          <input type="checkbox" bind:checked={headerAction} />
+          <span>Header button</span>
+        </label>
         <label class="toolbar-field">
           <span>Right button</span>
           <select class="canvas-toolbar-select" bind:value={rightOption}>

package/src/editor/component-editor/SectionDividerEditor.svelte

@@ -66,6 +66,7 @@
         legend: '',
         element: 'title',
         colorVariable: `--sectiondivider-${v}-title`,
+        colorCanBeLinked: true,
         familyVariable: `--sectiondivider-${v}-title-font-family`,
         sizeVariable: `--sectiondivider-${v}-title-font-size`,
         weightVariable: `--sectiondivider-${v}-title-font-weight`,
@@ -78,6 +79,7 @@
         legend: '',
         element: 'description',
         colorVariable: `--sectiondivider-${v}-description`,
+        colorCanBeLinked: true,
         familyVariable: `--sectiondivider-${v}-description-font-family`,
         sizeVariable: `--sectiondivider-${v}-description-font-size`,
         weightVariable: `--sectiondivider-${v}-description-font-weight`,
@@ -87,6 +89,7 @@
         legend: '',
         element: 'eyebrow',
         colorVariable: `--sectiondivider-${v}-eyebrow`,
+        colorCanBeLinked: true,
         familyVariable: `--sectiondivider-${v}-eyebrow-font-family`,
         sizeVariable: `--sectiondivider-${v}-eyebrow-font-size`,
         weightVariable: `--sectiondivider-${v}-eyebrow-font-weight`,
@@ -399,7 +402,7 @@
   }
 </script>
 
-<ComponentEditorBase {component} title="Section Divider" description="Full-width section banner. Each variant (lg/md/sm) is a full preset: its own size, typography, colors, AND intrinsic properties (alignment, hairline, eyebrow/description visibility)." tokens={allTokens} {linked} variants={variantOptions}>
+<ComponentEditorBase {component} title="Section Divider" description="Full-width section banner. Each variant (lg/md/sm) is a full preset: its own size, typography, colors, AND intrinsic properties (alignment, hairline, eyebrow/description visibility)." tokens={allTokens} {linked} variants={variantOptions} defaultVariant="md">
   {#each variants as v}
     <VariantGroup
       name={v.key}

package/src/editor/component-editor/SideNavigationEditor.svelte

@@ -48,6 +48,8 @@
       { label: 'surface color', groupKey: 'title-surface', variable: `--sidenavigation-title-${s}-surface` },
       { label: 'border color', groupKey: 'title-border', variable: `--sidenavigation-title-${s}-border` },
       { label: 'border width', canBeLinked: true, groupKey: 'title-border-width', variable: `--sidenavigation-title-${s}-border-width` },
+      { label: 'indicator color', groupKey: 'title-accent', variable: `--sidenavigation-title-${s}-accent` },
+      { label: 'indicator width', canBeLinked: true, groupKey: 'title-accent-width', variable: `--sidenavigation-title-${s}-accent-width` },
       { label: 'padding', canBeLinked: true, groupKey: 'title-padding', variable: `--sidenavigation-title-${s}-padding` },
     ];
   }
@@ -59,6 +61,8 @@
     { label: 'gap', canBeLinked: true, groupKey: 'title-gap', variable: '--sidenavigation-title-gap' },
     { label: 'corner radius', canBeLinked: true, groupKey: 'title-radius', variable: '--sidenavigation-title-radius' },
     { label: 'label surface color', groupKey: 'title-label-surface', variable: '--sidenavigation-title-label-surface' },
+    { label: 'label border color', groupKey: 'title-label-border', variable: '--sidenavigation-title-label-border' },
+    { label: 'label border width', canBeLinked: true, groupKey: 'title-label-border-width', variable: '--sidenavigation-title-label-border-width' },
     { label: 'label corner radius', canBeLinked: true, groupKey: 'title-label-radius', variable: '--sidenavigation-title-label-radius' },
     { label: 'label padding', canBeLinked: true, groupKey: 'title-label-padding', variable: '--sidenavigation-title-label-padding' },
   ];
@@ -214,6 +218,7 @@
   const linkableContexts = new Map<string, string>([
     ...STATEFUL_STATES.flatMap((s): Array<[string, string]> => [
       [`--sidenavigation-title-${s}-border-width`, `title ${s}`],
+      [`--sidenavigation-title-${s}-accent-width`, `title ${s}`],
       [`--sidenavigation-title-${s}-padding`, `title ${s}`],
       [`--sidenavigation-title-${s}-label-font-family`, `title ${s}`],
       [`--sidenavigation-title-${s}-label-font-size`, `title ${s}`],
@@ -252,6 +257,7 @@
     ]),
     ['--sidenavigation-panel-border-width', 'panel'],
     ['--sidenavigation-panel-padding', 'panel'],
+    ['--sidenavigation-title-label-border-width', 'title block'],
   ]);
 </script>
 

package/src/editor/component-editor/TabBarEditor.svelte

@@ -19,6 +19,7 @@
       { label: 'border width', element: 'frame', canBeLinked: true, groupKey: 'tab-border-width', variable: `--tabbar-${s}-tab-border-width` },
       { label: 'padding', element: 'frame', canBeLinked: true, groupKey: 'padding', variable: `--tabbar-${s}-padding` },
       { label: 'size', element: 'icon', canBeLinked: true, groupKey: 'icon-size', variable: `--tabbar-${s}-icon-size` },
+      { label: 'color', element: 'indicator', groupKey: 'indicator-color', variable: `--tabbar-${s}-border` },
       { label: 'width', element: 'indicator', canBeLinked: true, groupKey: 'indicator-border-width', variable: `--tabbar-${s}-indicator-border-width` },
     ];
   }
@@ -50,10 +51,6 @@
     ],
     ...Object.fromEntries(tabStateNames.map((s) => [`${s} tab`, tabStateTokens(s)])),
   };
-  states['active tab'] = [
-    ...states['active tab'],
-    { label: 'color', element: 'indicator', groupKey: 'indicator-color', variable: '--tabbar-active-border' },
-  ];
   const typeGroups: Record<string, TypeGroupConfig[]> = Object.fromEntries(
     tabStateNames.map((s) => [`${s} tab`, tabStateTypeGroups(s)]),
   );
@@ -71,7 +68,6 @@
 
   // Linking: shape props across tab states (same tab object).
   const linkableContexts = new Map<string, string>([
-    [`--tabbar-active-border`, `active tab`] as const,
     ...tabStateNames.flatMap((s) => [
     [`--tabbar-${s}-tab-border-color`, `${s} tab`] as const,
     [`--tabbar-${s}-tab-border-width`, `${s} tab`] as const,

package/src/editor/component-editor/scaffolding/ComponentEditorBase.svelte

@@ -25,6 +25,9 @@
       with 2+ entries, a single variant tab strip is rendered that drives which
       VariantGroup is focused. */
     variants?: { value: string; label: string }[];
+    /** Variant selected when this component editor first opens. Falls back to
+      the first declared variant. */
+    defaultVariant?: string;
     config?: import('svelte').Snippet;
     children?: import('svelte').Snippet<[any]>;
   }
@@ -36,6 +39,7 @@
     tokens = [],
     linked = null,
     variants = [],
+    defaultVariant = '',
     config,
     children
   }: Props = $props();
@@ -52,7 +56,10 @@
   let showVariantTabs = $derived(variants.length >= 2);
   run(() => {
     if (showVariantTabs && ($focusedVariant === null || !variants.some((v) => v.value === $focusedVariant))) {
-      focusedVariant.set(variants[0].value);
+      const preferred = variants.some((v) => v.value === defaultVariant)
+        ? defaultVariant
+        : variants[0].value;
+      focusedVariant.set(preferred);
     }
   });
   let resetVariables = $derived(tokens.map((t) => t.variable));

package/src/editor/component-editor/scaffolding/ComponentFileManager.svelte

@@ -5,10 +5,7 @@
 <script lang="ts">
   import { onMount, onDestroy } from 'svelte';
   import UIInfoPopover from '../../ui/UIInfoPopover.svelte';
-  import { get } from 'svelte/store';
   import type {
-    AliasDiskValue,
-    ComponentConfig,
     ComponentConfigMeta,
     LiveSource,
   } from '../../core/themes/themeTypes';
@@ -19,6 +16,7 @@
     saveComponentConfig,
     deleteComponentConfig,
     writeWorkingComponentConfig,
+    componentConfigFromState,
   } from '../../core/components/componentConfigService';
   import {
     editorState,
@@ -42,8 +40,6 @@
     saveAsTheme,
   } from '../../core/themes/themeService';
   import type { ThemeMeta } from '../../core/themes/themeTypes';
-  import { CURRENT_COMPONENT_SCHEMA_VERSION } from '../../core/themes/migrations';
-  import { refToDiskValue } from '../../core/store/cssVarRef';
   import { safeFetch } from '../../core/storage/storage';
   import { API_BASE } from '../../core/storage/apiBase';
   import { flashStatus } from '../../core/flashStatus';
@@ -182,36 +178,14 @@
     }
   }
 
-  function currentAliases(): Record<string, AliasDiskValue> {
-    const slice = get(editorState).components[component];
-    if (!slice) return {};
-    const out: Record<string, AliasDiskValue> = {};
-    for (const [k, ref] of Object.entries(slice.aliases)) out[k] = refToDiskValue(ref);
-    return out;
-  }
-
-  function currentConfig(): Record<string, unknown> {
-    return get(editorState).components[component]?.config ?? {};
-  }
-
-  function currentConfigData(displayName: string): ComponentConfig {
-    const now = new Date().toISOString();
-    return {
-      name: displayName,
-      component,
-      createdAt: now,
-      updatedAt: now,
-      aliases: { ...currentAliases() },
-      config: { ...currentConfig() },
-      schemaVersion: CURRENT_COMPONENT_SCHEMA_VERSION,
-    };
-  }
-
   /** Flush the editor state to the component's working buffer. A theme save
    *  captures the buffers, so this is what puts these edits in reach of Save
    *  and Adopt. */
   async function persist(): Promise<void> {
-    await writeWorkingComponentConfig(component, currentConfigData(openTheme.name));
+    await writeWorkingComponentConfig(
+      component,
+      componentConfigFromState($editorState, component, openTheme.name),
+    );
     liveSource = 'working';
     markComponentSaved(component);
     bumpComponentActiveRevision();
@@ -237,7 +211,11 @@
     const { displayName, fileName } = detail;
     saveStatus = 'saving';
     try {
-      await saveComponentConfig(component, fileName, currentConfigData(displayName));
+      await saveComponentConfig(
+        component,
+        fileName,
+        componentConfigFromState($editorState, component, displayName),
+      );
       await persist();
       flashStatus(setSaveStatus, 'saved');
       await refreshFiles();

package/src/editor/component-editor/scaffolding/StateBlock.svelte

@@ -129,6 +129,7 @@
                 legend={tg.legend ?? ''}
                 colorVariable={tg.colorVariable}
                 colorLabel={tg.colorLabel ?? 'text color'}
+                colorCanBeLinked={tg.colorCanBeLinked ?? false}
                 familyVariable={tg.familyVariable}
                 familyLabel={tg.familyLabel ?? 'font family'}
                 sizeVariable={tg.sizeVariable}
@@ -171,6 +172,7 @@
           legend={tg.legend ?? 'type'}
           colorVariable={tg.colorVariable}
           colorLabel={tg.colorLabel ?? 'text color'}
+          colorCanBeLinked={tg.colorCanBeLinked ?? false}
           familyVariable={tg.familyVariable}
           familyLabel={tg.familyLabel ?? 'font family'}
           sizeVariable={tg.sizeVariable}

package/src/editor/component-editor/scaffolding/TypeEditor.svelte

@@ -15,6 +15,7 @@
   interface Props {
     colorVariable: string;
     colorLabel?: string;
+    colorCanBeLinked?: boolean;
     familyVariable?: string | undefined;
     familyLabel?: string;
     sizeVariable?: string | undefined;
@@ -42,6 +43,7 @@
   let {
     colorVariable,
     colorLabel = 'color',
+    colorCanBeLinked = false,
     familyVariable = undefined,
     familyLabel = 'family',
     sizeVariable = undefined,
@@ -65,7 +67,7 @@
 <FieldsetWrapper {legend}>
   <div class="type-grid">
     <span class="row-label">{colorLabel}</span>
-    <UIPaletteSelector variable={colorVariable} {component} {onchange} />
+    <UIPaletteSelector variable={colorVariable} {component} canBeLinked={colorCanBeLinked} {onchange} />
 
     {#if familyVariable}
       <span class="row-label">{familyLabel}</span>

package/src/editor/component-editor/scaffolding/types.ts

@@ -70,6 +70,9 @@ export type TypeGroupConfig = {
   legend?: string;
   colorVariable: string;
   colorLabel?: string;
+  /** Whether this typography color participates in its declared cross-context
+   *  sibling group. Kept explicit because most state colors are independent. */
+  colorCanBeLinked?: boolean;
   familyVariable?: string;
   familyLabel?: string;
   sizeVariable?: string;

package/src/editor/core/components/componentConfigService.ts

@@ -1,7 +1,10 @@
 import type { ComponentConfig, ComponentConfigMeta, LiveSource } from '../themes/themeTypes';
+import type { EditorState } from '../store/editorTypes';
 import { versionedFileResource } from '../storage/files/versionedFileResourceClient';
 import { API_BASE } from '../storage/apiBase';
 import { liveMovedSinceBake } from '../productionPulse';
+import { CURRENT_COMPONENT_SCHEMA_VERSION } from '../themes/migrations';
+import { refToDiskValue } from '../store/cssVarRef';
 
 /**
  * REST client for per-component config files. Parallel to `colorsAndTypeService.ts`
@@ -59,6 +62,28 @@ export const deleteComponentConfig = (component: string, fileName: string): Prom
 export const getActiveComponentConfig = (component: string): Promise<ComponentConfig | null> =>
   resourceFor(component).getActive();
 
+/** Serialize one live component slice into the on-disk config shape. Shared by
+ * the component editor's local checkpoint and the theme-level save-all flow. */
+export function componentConfigFromState(
+  state: EditorState,
+  component: string,
+  displayName: string,
+): ComponentConfig {
+  const now = new Date().toISOString();
+  const slice = state.components[component];
+  return {
+    name: displayName,
+    component,
+    createdAt: now,
+    updatedAt: now,
+    aliases: Object.fromEntries(
+      Object.entries(slice?.aliases ?? {}).map(([name, ref]) => [name, refToDiskValue(ref)]),
+    ),
+    config: { ...(slice?.config ?? {}) },
+    schemaVersion: CURRENT_COMPONENT_SCHEMA_VERSION,
+  };
+}
+
 /** Write the component's unsaved buffer. */
 export async function writeWorkingComponentConfig(
   component: string,

package/src/editor/core/cssVarSync.ts

@@ -4,8 +4,10 @@
  * Writes to document.documentElement and — when running inside a same-origin
  * iframe (the live-preview overlay) — also writes to
  * window.parent.document.documentElement. This lets the overlay editor at
- * /live-tokens/editor drive the host site's :root in real time without any
- * message-passing infrastructure.
+ * /live-tokens/editor drive the host site's :root for ordinary live edits.
+ * Complete theme application additionally synchronizes each document's typed
+ * Svelte store through `themeDocumentSync`; copying CSS alone would leave an
+ * already-open editor disconnected when the load originates in the host.
  *
  * When the editor runs standalone at /live-tokens/editor (not inside the overlay iframe),
  * parentRoot is null and every call is a plain single-root write.
@@ -64,10 +66,54 @@ export function getSyncedDocuments(): Document[] {
 }
 
 export const CSS_VAR_CHANGE_EVENT = 'cssvar:change';
+/** One notification for a completed CSS-variable transaction. Internal editor
+ * controls use this instead of reacting once per variable during theme loads. */
+export const CSS_VARS_CHANGE_EVENT = 'cssvars:change';
+
+export interface CssVarsChangeDetail {
+  names: string[];
+}
+
+let batchDepth = 0;
+const pendingNames = new Set<string>();
+
+function dispatchChanges(names: string[]): void {
+  if (typeof document === 'undefined' || names.length === 0) return;
+  document.dispatchEvent(new CustomEvent<CssVarsChangeDetail>(CSS_VARS_CHANGE_EVENT, {
+    detail: { names },
+  }));
+  // Preserve the public per-variable contract for consumers. These events are
+  // deliberately dispatched only after every write in a batch has landed, so
+  // a listener's computed-style read cannot force layout against a half-painted
+  // theme.
+  for (const name of names) {
+    document.dispatchEvent(new CustomEvent(CSS_VAR_CHANGE_EVENT, { detail: { name } }));
+  }
+}
 
 function notifyChange(name: string): void {
-  if (typeof document === 'undefined') return;
-  document.dispatchEvent(new CustomEvent(CSS_VAR_CHANGE_EVENT, { detail: { name } }));
+  if (batchDepth > 0) {
+    pendingNames.add(name);
+    return;
+  }
+  dispatchChanges([name]);
+}
+
+/** Run a group of CSS-variable writes as one observable transaction. DOM
+ * styles are still applied synchronously; notifications wait until the outer
+ * batch completes. Nested batches coalesce into their parent. */
+export function batchCssVarChanges<T>(fn: () => T): T {
+  batchDepth += 1;
+  try {
+    return fn();
+  } finally {
+    batchDepth -= 1;
+    if (batchDepth === 0 && pendingNames.size > 0) {
+      const names = Array.from(pendingNames);
+      pendingNames.clear();
+      dispatchChanges(names);
+    }
+  }
 }
 
 export function setCssVar(name: string, value: string): void {
@@ -86,9 +132,11 @@ export function removeCssVar(name: string): void {
 
 /** Apply a map of CSS variables to :root (and the parent :root when in an iframe). */
 export function applyCssVariables(variables: Record<string, string>): void {
-  for (const [name, value] of Object.entries(variables)) {
-    setCssVar(name, value);
-  }
+  batchCssVarChanges(() => {
+    for (const [name, value] of Object.entries(variables)) {
+      setCssVar(name, value);
+    }
+  });
 }
 
 /** Remove all inline CSS custom properties from :root on both self and parent. */
@@ -122,3 +170,13 @@ export function scrapeCssVariables(): Record<string, string> {
   }
   return variables;
 }
+
+/** Test-only: forget cached window/document roots so a test can install a
+ *  synthetic same-origin parent before the next write resolves them. */
+export function __resetCssVarSyncForTests(): void {
+  selfRoot = null;
+  parentRoot = null;
+  resolved = false;
+  batchDepth = 0;
+  pendingNames.clear();
+}

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

@@ -6,7 +6,7 @@ import type {
   FontStackVariable,
   SystemCascadePreset,
 } from '../themes/themeTypes';
-import { setCssVar, getSyncedDocuments } from '../cssVarSync';
+import { setCssVar, removeCssVar, getSyncedDocuments } from '../cssVarSync';
 
 export const SYSTEM_CASCADES: Record<SystemCascadePreset, string> = {
   'system-ui-sans':
@@ -15,6 +15,13 @@ export const SYSTEM_CASCADES: Record<SystemCascadePreset, string> = {
   'system-ui-mono': 'ui-monospace, "SF Mono", Menlo, Consolas, monospace',
 };
 
+const FONT_STACK_VARIABLES: FontStackVariable[] = [
+  '--font-display',
+  '--font-sans',
+  '--font-serif',
+  '--font-mono',
+];
+
 const LINK_ATTR = 'data-font-source-id';
 const STYLE_ATTR = 'data-font-source-id';
 
@@ -124,7 +131,9 @@ export function resolveFontStackValues(
  */
 export function applyFontStacks(stacks: FontStack[], sources: FontSource[]): void {
   const resolved = resolveFontStackValues(stacks, sources);
-  for (const [name, value] of Object.entries(resolved)) {
-    setCssVar(name, value);
+  for (const name of FONT_STACK_VARIABLES) {
+    const value = resolved[name];
+    if (value) setCssVar(name, value);
+    else removeCssVar(name);
   }
 }