@motion-proto/live-tokens 0.7.1 → 0.9.0

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

@@ -30,6 +30,10 @@
     stateActions?: Snippet<[string]>;
     previewActions?: Snippet;
     compositeControls?: Snippet<[string]>;
+    /** Each child should be a `.property-row`. Rendered above the token grid
+        so per-variant display knobs (alignment, hairline, etc.) lead the list
+        before the typography and token rows. */
+    extraPropertyRowsTop?: Snippet<[string]>;
     /** Each child should be a `.property-row` to match the token grid above. */
     extraPropertyRows?: Snippet<[string]>;
     /** Extra sections appended below the Background controls inside the canvas
@@ -37,6 +41,13 @@
         Background. Lets per-instance display knobs (anchor, alignment, etc.)
         live with the canvas rather than in a separate config block above. */
     canvasToolbarExtras?: Snippet;
+    /** Per-element Show toggles, forwarded to StateBlock. Keyed by element name. */
+    elementToggles?: Record<string, { checked: boolean; label?: string; onchange: (checked: boolean) => void }>;
+    /** Explicit order for element-grouped sections, forwarded to StateBlock. */
+    elementOrder?: string[];
+    /** Per-element extras snippet, forwarded to StateBlock. Receives the
+        element name and renders between the section heading and its content. */
+    elementExtras?: Snippet<[string]>;
     /** Skip the default centered, padded stage when the editor brings its own backdrop. */
     unboxedPreview?: boolean;
     backdropPadding?: string;
@@ -58,8 +69,12 @@
     stateActions,
     previewActions,
     compositeControls,
+    extraPropertyRowsTop,
     extraPropertyRows,
     canvasToolbarExtras,
+    elementToggles,
+    elementOrder,
+    elementExtras,
     unboxedPreview = false,
     backdropPadding,
     backdropModes,
@@ -78,7 +93,7 @@
 
   let activeTab: string = $state('');
 
-  const TYPE_PROPS = ['colorVariable', 'familyVariable', 'sizeVariable', 'weightVariable', 'lineHeightVariable', 'outlineWidthVariable', 'outlineColorVariable'] as const;
+  const TYPE_PROPS = ['colorVariable', 'familyVariable', 'sizeVariable', 'weightVariable', 'lineHeightVariable', 'letterSpacingVariable', 'outlineWidthVariable', 'outlineColorVariable'] as const;
   // Carry per-side derived vars so split padding fully transfers; no-op when absent.
   const PADDING_SIDES = ['top', 'right', 'bottom', 'left'] as const;
 
@@ -124,6 +139,25 @@
       skips these in the typeGroups copy loop. */
   const COLOR_TYPE_PROPS = new Set(['colorVariable', 'outlineColorVariable']);
 
+  /** True iff `colorRef` is a CSS-var token whose slug contains `family`
+      as a hyphen-delimited segment (e.g. `--surface-canvas-low` ∋ `canvas`). */
+  function stopMatchesFamily(colorRef: string, family: string): boolean {
+    if (!colorRef.startsWith('--')) return false;
+    return colorRef.slice(2).split('-').includes(family);
+  }
+
+  /** Replace the first `from` segment in a CSS-var token slug with `to`.
+      Used to swap stop colors across variant families on gradient copy
+      (e.g. `--surface-success-high` + (success → accent) → `--surface-accent-high`). */
+  function swapFamilyInToken(colorRef: string, from: string, to: string): string {
+    if (!colorRef.startsWith('--')) return colorRef;
+    const parts = colorRef.slice(2).split('-');
+    const idx = parts.indexOf(from);
+    if (idx < 0) return colorRef;
+    parts[idx] = to;
+    return '--' + parts.join('-');
+  }
+
   function pickCopySource(toState: string, fromVariant: string, fromState: string) {
     const preserveColorFamily = $preserveColorFamilyStore;
     if (!component || !states) return;
@@ -139,11 +173,15 @@
       const slice = s.components[component!] ?? (s.components[component!] = { activeFile: 'default', aliases: {}, config: {} });
       const dstVarsTouched: string[] = [];
       /** Resolve a variable's effective value as a CSS string: the override if
-          set, otherwise its declared default. Returns null if neither exists. */
+          set, otherwise its declared default. Returns null if neither exists.
+          Gradient refs short-circuit to null — the copy path for gradients
+          uses `applyGradient`, not the alpha-extract pipeline. */
       const effectiveValue = (varName: string): string | null => {
         const ref = slice.aliases[varName];
-        if (ref) return ref.kind === 'token' ? `var(${ref.name})` : ref.value;
-        return getDeclaredValue(varName);
+        if (!ref) return getDeclaredValue(varName);
+        if (ref.kind === 'token') return `var(${ref.name})`;
+        if (ref.kind === 'literal') return ref.value;
+        return null;
       };
 
       const apply = (srcVar: string, dstVar: string) => {
@@ -179,10 +217,49 @@
         };
         dstVarsTouched.push(dstVar);
       };
+      /** Copy a structured gradient ref. Stops carry source's positions +
+          opacities verbatim; out-of-family stop colors carry verbatim too.
+          With preserveColorFamily on, in-family stop colors swap to the
+          destination family — see plan §5 for the worked example. */
+      const applyGradient = (
+        srcVar: string,
+        dstVar: string,
+        srcFamily: string | undefined,
+        dstFamily: string | undefined,
+      ) => {
+        const srcRef = slice.aliases[srcVar];
+        if (!srcRef || srcRef.kind !== 'gradient') {
+          // Source has no override — clearing dst returns it to its own CSS
+          // default (which is dst's family by design), preserving the
+          // "destination keeps its family palette" invariant.
+          delete slice.aliases[dstVar];
+          dstVarsTouched.push(dstVar);
+          return;
+        }
+        const swapFamilies = preserveColorFamily
+          && !!srcFamily && !!dstFamily
+          && srcFamily !== dstFamily;
+        const newStops = srcRef.value.stops.map((s) => {
+          if (swapFamilies && stopMatchesFamily(s.color, srcFamily!)) {
+            return { ...s, color: swapFamilyInToken(s.color, srcFamily!, dstFamily!) };
+          }
+          return { ...s };
+        });
+        slice.aliases[dstVar] = {
+          kind: 'gradient',
+          value: { type: srcRef.value.type, angle: srcRef.value.angle, stops: newStops },
+        };
+        dstVarsTouched.push(dstVar);
+      };
+
       const minLen = Math.min(srcTokens.length, dstTokens.length);
       for (let i = 0; i < minLen; i++) {
         const srcVar = srcTokens[i].variable;
         const dstVar = dstTokens[i].variable;
+        if (srcTokens[i].kind === 'gradient' || dstTokens[i].kind === 'gradient') {
+          applyGradient(srcVar, dstVar, srcTokens[i].family, dstTokens[i].family);
+          continue;
+        }
         if (preserveColorFamily && isColorToken(srcTokens[i])) {
           applyColorPreserve(srcVar, dstVar);
           continue;
@@ -231,7 +308,45 @@
   });
 
   let stateNames = $derived(states ? Object.keys(states) : []);
+  /** Key-name convention: when ANY state name contains " / ", the strip switches
+      to two-tier rendering — top row is parts (unique left-hand sides), bottom
+      row is the active part's states (right-hand sides). Parts with no slash
+      have no sub-states and skip the bottom row when active. */
+  const PART_SEP = ' / ';
+  let isHierarchical = $derived(stateNames.some((n) => n.includes(PART_SEP)));
+  /** Ordered list of unique parts, preserving the order they first appear in `states`. */
+  let parts = $derived.by(() => {
+    const seen: string[] = [];
+    for (const n of stateNames) {
+      const part = n.includes(PART_SEP) ? n.split(PART_SEP)[0] : n;
+      if (!seen.includes(part)) seen.push(part);
+    }
+    return seen;
+  });
+  /** Sub-states of the currently active part (only meaningful in hierarchical mode). */
+  let activePart = $derived(activeTab.includes(PART_SEP) ? activeTab.split(PART_SEP)[0] : activeTab);
+  let activeSubState = $derived(activeTab.includes(PART_SEP) ? activeTab.split(PART_SEP)[1] : '');
+  let partSubStates = $derived(
+    isHierarchical
+      ? stateNames.filter((n) => n.startsWith(activePart + PART_SEP)).map((n) => n.split(PART_SEP)[1])
+      : [],
+  );
   let tabsStripVisible = $derived(stateNames.length >= 2);
+  let subStripVisible = $derived(isHierarchical && partSubStates.length >= 2);
+
+  /** Switch parts. If the new part has sub-states, jump to its first one; otherwise
+      activate the part itself. Keeps activeTab as a single canonical key so the
+      downstream property lookup, copy-from menus, and focusedStateStore stay simple. */
+  function selectPart(part: string) {
+    const firstSub = stateNames.find((n) => n.startsWith(part + PART_SEP));
+    activeTab = firstSub ?? part;
+    focusedStateStore.set(activeTab);
+  }
+  function selectSubState(sub: string) {
+    activeTab = `${activePart}${PART_SEP}${sub}`;
+    focusedStateStore.set(activeTab);
+  }
+
   $effect(() => {
     if (stateNames.length > 0 && !stateNames.includes(activeTab)) {
       activeTab = stateNames[0];
@@ -297,30 +412,62 @@
           {@render children?.({ activeState: activeTab })}
         </ShadowBackdrop>
       {/if}
-    </div>
 
-    {#if tabsStripVisible}
-      <div class="tabs-states-block">
-        <span class="editor-subsection-title">{selectorLabel}</span>
-        <div class="tabs-selectors">
-          <div class="state-tabs" role="tablist">
-            {#each stateNames as s}
-              <button
-                type="button"
-                class="state-tab-btn"
-                class:active={activeTab === s}
-                role="tab"
-                aria-selected={activeTab === s}
-                onclick={() => { activeTab = s; focusedStateStore.set(s); }}
-              >{s}</button>
-            {/each}
+      {#if tabsStripVisible}
+        <div class="tabs-states-block">
+          <span class="editor-subsection-title">{selectorLabel}</span>
+          <div class="tabs-selectors">
+            {#if isHierarchical}
+              <div class="state-tabs" role="tablist">
+                {#each parts as p}
+                  <button
+                    type="button"
+                    class="state-tab-btn"
+                    class:active={activePart === p}
+                    role="tab"
+                    aria-selected={activePart === p}
+                    onclick={() => selectPart(p)}
+                  >{p}</button>
+                {/each}
+              </div>
+            {:else}
+              <div class="state-tabs" role="tablist">
+                {#each stateNames as s}
+                  <button
+                    type="button"
+                    class="state-tab-btn"
+                    class:active={activeTab === s}
+                    role="tab"
+                    aria-selected={activeTab === s}
+                    onclick={() => { activeTab = s; focusedStateStore.set(s); }}
+                  >{s}</button>
+                {/each}
+              </div>
+            {/if}
+            {#if activeTab}
+              {@render stateActions?.(activeTab)}
+            {/if}
           </div>
-          {#if activeTab}
-            {@render stateActions?.(activeTab)}
+          {#if subStripVisible}
+            <div class="tabs-selectors substrip">
+              <span class="editor-subsection-title state-eyebrow">State</span>
+              <div class="state-tabs" role="tablist">
+                {#each partSubStates as s}
+                  <button
+                    type="button"
+                    class="state-tab-btn"
+                    class:active={activeSubState === s}
+                    role="tab"
+                    aria-selected={activeSubState === s}
+                    onclick={() => selectSubState(s)}
+                  >{s}</button>
+                {/each}
+              </div>
+            </div>
           {/if}
         </div>
-      </div>
-    {/if}
+      {/if}
+    </div>
 
     {#if activeTab && states[activeTab]}
       {@const stateName = activeTab}
@@ -339,12 +486,20 @@
           />
         {/if}
       </div>
+      {#if extraPropertyRowsTop}
+        <div class="extra-property-rows extra-property-rows--top">
+          {@render extraPropertyRowsTop(stateName)}
+        </div>
+      {/if}
       <StateBlock
         tokens={states[stateName]}
         typeGroups={typeGroups[stateName] ?? []}
         {component}
         {linkedOrder}
         {columns}
+        {elementToggles}
+        {elementOrder}
+        {elementExtras}
         {onchange}
       />
       {#if extraPropertyRows}
@@ -377,12 +532,46 @@
   /* Card chrome lives on .editor-section-card in ui-editor.css. */
   .variant-group {
     gap: var(--ui-space-12);
+    container-type: inline-size;
+    container-name: variant-group;
   }
 
+  /* Pin the preview + state-tab strip to the top of the page scroll so
+     property edits stay visually connected to the preview without scrolling.
+     The card background extends through the sticky band so the property grid
+     scrolls cleanly behind it. The element-grouped property layout (see
+     StateBlock) fans out horizontally, which keeps the property section
+     short enough that the sticky preview rarely steals usable space. */
   .tabs-preview {
+    position: sticky;
+    top: 0;
+    z-index: 2;
     display: flex;
     flex-direction: column;
     gap: var(--ui-space-20);
+    background: var(--ui-surface-low);
+    /* Bleed the background up through the card's top padding so content
+       scrolling behind doesn't peek between the viewport edge and the
+       pinned preview. The matching negative margin restores flow position.
+       Border-radius hugs the card's rounded top corners so the unpinned
+       state still reads as one continuous panel. */
+    margin: calc(-1 * var(--ui-space-20)) calc(-1 * var(--ui-space-20)) 0;
+    padding: var(--ui-space-20) var(--ui-space-20) 0;
+    border-radius: var(--ui-radius-md) var(--ui-radius-md) 0 0;
+  }
+
+  /* Soft fade at the bottom of the sticky band so property rows scrolling
+     up don't sharply cut against the pinned preview. Greyscale (no accent).
+     Sits below the preview body, above scrolling content. */
+  .tabs-preview::after {
+    content: '';
+    position: absolute;
+    left: 0;
+    right: 0;
+    bottom: calc(-1 * var(--ui-space-12));
+    height: var(--ui-space-12);
+    background: linear-gradient(to bottom, var(--ui-surface-low), transparent);
+    pointer-events: none;
   }
 
   .preview-header {
@@ -416,6 +605,13 @@
     box-sizing: border-box;
   }
 
+  @container variant-group (max-width: 32rem) {
+    .canvas-toolbar {
+      width: 100%;
+      height: auto;
+    }
+  }
+
   .canvas-toolbar :global(.canvas-toolbar-eyebrow) {
     font-size: var(--ui-font-size-xs);
     font-weight: var(--ui-font-weight-medium);
@@ -441,6 +637,7 @@
      vocabulary from the rest of the editor. */
   .canvas-toolbar :global(.canvas-toolbar-select) {
     width: 100%;
+    box-sizing: border-box;
     appearance: none;
     -webkit-appearance: none;
     padding: 0 var(--ui-space-24) 0 var(--ui-space-8);
@@ -466,9 +663,14 @@
     outline-offset: 2px;
   }
 
-  /* Native <input> styled to match the toolbar's select chrome. */
+  /* Native <input> styled to match the toolbar's select chrome. Long values
+     ellipsize when blurred so the input doesn't grow or scroll-bleed past
+     the toolbar's 11rem column; focus restores native caret-driven scroll. */
   .canvas-toolbar :global(.canvas-toolbar-input) {
     width: 100%;
+    min-width: 0;
+    max-width: 100%;
+    box-sizing: border-box;
     padding: 0 var(--ui-space-8);
     min-height: 1.75rem;
     background: var(--ui-surface-low);
@@ -477,6 +679,7 @@
     color: var(--ui-text-primary);
     font-family: var(--ui-font-sans);
     font-size: var(--ui-font-size-sm);
+    text-overflow: ellipsis;
     transition: background-color var(--ui-transition-fast), border-color var(--ui-transition-fast);
   }
   .canvas-toolbar :global(.canvas-toolbar-input:hover) {
@@ -572,6 +775,17 @@
     gap: var(--ui-space-12);
   }
 
+  /* Sub-strip sits flush under the parts strip when a part has interaction states.
+     The eyebrow label distinguishes it from the parts row above. */
+  .tabs-selectors.substrip {
+    margin-top: var(--ui-space-6);
+  }
+  .tabs-selectors.substrip .state-eyebrow {
+    color: var(--ui-text-tertiary);
+    font-size: var(--ui-font-size-xs);
+    min-width: 2.5rem;
+  }
+
   .state-tabs {
     display: inline-flex;
     flex-wrap: wrap;

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

@@ -7,6 +7,7 @@ export const TYPE_FONT_PROPS = [
   { key: 'sizeVariable', label: 'font size', defaultGroupKey: 'font-size' },
   { key: 'weightVariable', label: 'font weight', defaultGroupKey: 'font-weight' },
   { key: 'lineHeightVariable', label: 'line height', defaultGroupKey: 'line-height' },
+  { key: 'letterSpacingVariable', label: 'letter spacing', defaultGroupKey: 'letter-spacing' },
 ] as const satisfies ReadonlyArray<{
   key: keyof TypeGroupConfig;
   label: string;

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

@@ -1,9 +1,9 @@
-import { componentRegistry } from '../registry';
+import { getComponentRegistry } from '../registry';
 
 /**
  * Resolve a component id to its runtime source file path. Reads from the
- * single component registry — no parallel mapping to maintain.
+ * merged component registry (built-ins + runtime registrations).
  */
 export function componentSourceFile(component: string): string {
-  return componentRegistry[component as keyof typeof componentRegistry]?.sourceFile ?? '';
+  return getComponentRegistry()[component]?.sourceFile ?? '';
 }

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

@@ -1,16 +1,21 @@
 import type { ComponentSection } from './componentSectionType';
-import { componentRegistryEntries } from '../registry';
+import { getComponentRegistryEntries } from '../registry';
 
 /**
- * Default editor sections — derived from the single component registry. Each
+ * Default editor sections — derived from the merged component registry. Each
  * section's `id` is the canonical lowercase component id (matches the runtime
- * filename, server scan, and `setComponentAlias` key); `label` is the
- * display string; `component` is the editor Svelte component.
+ * filename, server scan, and `setComponentAlias` key); `label` is the display
+ * string; `component` is the editor Svelte component.
  *
- * To add or reorder sections, edit `src/component-editor/registry.ts`.
+ * Recomputed on each call so consumer-registered components (added via
+ * `registerComponent()`) appear after the first-party set in iteration order.
+ *
+ * To add or reorder first-party sections, edit `src/editor/component-editor/registry.ts`.
  */
-export const defaultSections: ComponentSection[] = componentRegistryEntries.map((entry) => ({
-  id: entry.id,
-  label: entry.label,
-  component: entry.editorComponent,
-}));
+export function getDefaultSections(): ComponentSection[] {
+  return getComponentRegistryEntries().map((entry) => ({
+    id: entry.id,
+    label: entry.label,
+    component: entry.editorComponent,
+  }));
+}

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

@@ -24,6 +24,15 @@ export type Token = {
       StateBlock partitions the panel into labeled subsections — typography
       and properties for each element render together. */
   element?: string;
+  /** Hint to the editor that this token's alias is a structured payload
+      (currently only `kind: 'gradient'`). Drives Copy-from's per-kind
+      branch — gradient aliases need family-swap of in-family stop colors
+      rather than a verbatim ref copy. */
+  kind?: 'gradient';
+  /** Color-family slug for this token's owning variant (e.g. `brand`,
+      `accent`). Set on gradient-kind tokens so Copy-from's family-swap
+      can compute the src→dst family substitution. */
+  family?: string;
 };
 
 /** Editor type-group: a fieldset containing a coordinated set of typography tokens
@@ -43,6 +52,8 @@ export type TypeGroupConfig = {
   weightLabel?: string;
   lineHeightVariable?: string;
   lineHeightLabel?: string;
+  letterSpacingVariable?: string;
+  letterSpacingLabel?: string;
   outlineWidthVariable?: string;
   outlineWidthLabel?: string;
   outlineColorVariable?: string;

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

@@ -4,9 +4,11 @@
 // migration that splits legacy single-bucket aliases into the new
 // {aliases, config} shape.
 //
-// What goes here: literal-valued knobs that don't translate to CSS vars
-// (e.g. Dialog's confirm/cancel variant string is consumed by Dialog.svelte
-// via `$editorState`, not via CSS cascade).
+// What goes here: literal-valued knobs that live in the config bucket rather
+// than the alias bucket. Some are runtime CSS values consumed by live
+// components via the cascade (see CASCADING_COMPONENT_CONFIG_KEYS below);
+// others are editor-only metadata that drive alias rewrites without ever
+// reaching :root.
 //
 // What does NOT go here: aliases whose values are themselves CSS-var refs
 // — even if the value space is constrained (e.g. `--button-shimmer` →
@@ -16,4 +18,21 @@
 export const KNOWN_COMPONENT_CONFIG_KEYS: ReadonlySet<string> = new Set([
   '--dialog-confirm-variant',
   '--dialog-cancel-variant',
+  // SectionDivider per-variant `color-family` is editor metadata that drives
+  // the family-swap rewrite on aliases. It is not a runtime CSS value, so it
+  // stays in the config bucket. The other intrinsics (align, hairline,
+  // eyebrow/description visibility, eyebrow text-transform) now flow through
+  // the alias bucket as cascading CSS vars — see the 2026-05-22 migration.
+  '--sectiondivider-lg-color-family',
+  '--sectiondivider-md-color-family',
+  '--sectiondivider-sm-color-family',
+]);
+
+// Subset of KNOWN_COMPONENT_CONFIG_KEYS that the renderer emits to :root as
+// CSS vars so live components can read them via the cascade. Editor-only
+// metadata (e.g. `--sectiondivider-*-color-family`, which drives an alias
+// rewrite rather than a runtime value) is intentionally excluded.
+export const CASCADING_COMPONENT_CONFIG_KEYS: ReadonlySet<string> = new Set([
+  '--dialog-confirm-variant',
+  '--dialog-cancel-variant',
 ]);

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

@@ -1,4 +1,4 @@
-import type { ComponentConfig, ComponentConfigMeta } from '../themes/themeTypes';
+import type { AliasDiskValue, ComponentConfig, ComponentConfigMeta } from '../themes/themeTypes';
 import { versionedFileResource } from '../storage/files/versionedFileResourceClient';
 
 /**
@@ -23,7 +23,7 @@ export interface ComponentSummary {
 export interface ComponentProductionInfo {
   fileName: string;
   name: string;
-  aliases: Record<string, string>;
+  aliases: Record<string, AliasDiskValue>;
 }
 
 export interface ComponentConfigList {

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

@@ -1,5 +1,5 @@
 import { get } from 'svelte/store';
-import type { ComponentConfig } from '../themes/themeTypes';
+import type { AliasDiskValue, ComponentConfig } from '../themes/themeTypes';
 import { editorState, markComponentSaved } from '../store/editorStore';
 import type { CssVarRef } from '../store/editorTypes';
 import { CURRENT_COMPONENT_SCHEMA_VERSION } from '../themes/migrations';
@@ -24,8 +24,10 @@ export type SaveActiveComponentResult =
   | { ok: true; fileName: string; displayName: string }
   | { ok: false; reason: 'default' | 'no-state' | 'error'; error?: unknown };
 
-function refToString(ref: CssVarRef): string {
-  return ref.kind === 'token' ? ref.name : ref.value;
+function refToDiskValue(ref: CssVarRef): AliasDiskValue {
+  if (ref.kind === 'token') return ref.name;
+  if (ref.kind === 'literal') return ref.value;
+  return { kind: 'gradient', value: ref.value };
 }
 
 export async function saveActiveComponentConfig(
@@ -43,8 +45,8 @@ export async function saveActiveComponentConfig(
     const displayName = active?.name ?? fileName;
 
     const now = new Date().toISOString();
-    const aliases: Record<string, string> = {};
-    for (const [k, ref] of Object.entries(slice.aliases)) aliases[k] = refToString(ref);
+    const aliases: Record<string, AliasDiskValue> = {};
+    for (const [k, ref] of Object.entries(slice.aliases)) aliases[k] = refToDiskValue(ref);
 
     const data: ComponentConfig = {
       name: displayName,

package/src/editor/core/manifests/manifestService.ts

@@ -1,4 +1,4 @@
-import type { Manifest, ManifestMeta, Theme, ComponentConfig } from '../themes/themeTypes';
+import type { Manifest, ManifestMeta, ManifestBundle, Theme, ComponentConfig } from '../themes/themeTypes';
 import { versionedFileResource } from '../storage/files/versionedFileResourceClient';
 import { listComponents } from '../components/componentConfigService';
 import { getActiveTheme } from '../themes/themeService';
@@ -40,8 +40,9 @@ export interface ApplyManifestResult {
 
 /**
  * Server-side atomic apply: validate every referenced file exists, flip the
- * theme + each component's `_active.json` pointer, mark the manifest active,
- * and return the resolved theme + component configs in one payload. Clients
+ * theme + each component's `_active.json` and `_production.json` pointers,
+ * sync tokens.css/fonts.css from the new theme, mark the manifest active, and
+ * return the resolved theme + component configs in one payload. Clients
  * usually follow with a full page reload — manifest load is a "blow up the
  * world" action.
  */
@@ -114,3 +115,57 @@ export async function saveActiveManifest(displayName?: string): Promise<void> {
   };
   await saveManifest(active._fileName, manifest);
 }
+
+export interface ImportManifestResult {
+  ok: boolean;
+  /** Final manifest filename (may be renamed if it collided with an existing one). */
+  manifest: string;
+  /** Keyed `theme:<orig>` / `componentConfig:<comp>/<orig>` / `manifest:<orig>` → final name. */
+  renames: Record<string, string>;
+}
+
+/**
+ * Fetch the manifest as a self-contained `ManifestBundle` and trigger a
+ * browser download. Hidden-anchor trick — no infrastructure beyond the
+ * existing GET `/api/manifests/:name/export` endpoint.
+ *
+ * See temp/manifest-robustness-plan.md §11.
+ */
+export async function exportManifest(fileName: string): Promise<void> {
+  const res = await fetch(`/api/manifests/${encodeURIComponent(fileName)}/export`);
+  if (!res.ok) {
+    const err = await res.json().catch(() => ({ error: 'Export failed' }));
+    throw new Error(err.error || 'Export failed');
+  }
+  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 `ManifestBundle` to the import endpoint. Server materialises the
+ * inlined theme + component configs as fresh files (renaming on collision),
+ * rewrites the manifest's pointers, and returns the final manifest name plus
+ * the rename map so the UI can surface what got renamed.
+ */
+export async function importManifest(bundle: ManifestBundle): Promise<ImportManifestResult> {
+  const res = await fetch('/api/manifests/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();
+}