@motion-proto/live-tokens 0.1.0 → 0.3.1

package/src/lib/parentRouteStore.ts

@@ -0,0 +1,42 @@
+import { writable, type Readable } from 'svelte/store';
+import { route } from './router';
+
+// Parent-window route, viewable from inside the editor iframe. Mirrors the
+// host page's route via postMessage from LiveEditorOverlay. When not in an
+// iframe, falls through to the local route store.
+
+const MSG_TYPE = 'lt:parent-route';
+
+function buildStore(): Readable<string> {
+  if (typeof window === 'undefined') return route;
+  if (window.parent === window) return route;
+
+  const inner = writable<string>('/');
+
+  // Best-effort initial read (same-origin in dev).
+  try {
+    inner.set(window.parent.location.pathname || '/');
+  } catch {
+    // cross-origin or sandboxed — wait for the first postMessage instead
+  }
+
+  window.addEventListener('message', (e: MessageEvent) => {
+    const data = e.data;
+    if (data && typeof data === 'object' && data.type === MSG_TYPE && typeof data.path === 'string') {
+      inner.set(data.path);
+    }
+  });
+
+  return inner;
+}
+
+export const parentRoute: Readable<string> = buildStore();
+
+export function postParentRoute(target: Window | null | undefined, path: string): void {
+  if (!target) return;
+  try {
+    target.postMessage({ type: MSG_TYPE, path }, '*');
+  } catch {
+    // ignore — iframe may not be ready yet
+  }
+}

package/src/lib/parsers/globalRootBlock.ts

@@ -0,0 +1,32 @@
+/**
+ * Shared parser for `:global(:root) { ... }` declaration blocks in Svelte
+ * component sources.
+ *
+ * Both the browser-side `tokenRegistry` (Vite `?raw` import-time scrape) and
+ * the Node-side `themeFileApi` plugin (filesystem read on dev/HMR) need to
+ * recover Layer-2 component-token declarations from `.svelte` files. They had
+ * been carrying separate copies of the same regex; this is the canonical
+ * implementation that both targets import.
+ *
+ * Assumes no nested braces inside the block — Layer-2 token blocks are flat
+ * declaration lists (`--name: value;`), not nested rulesets. If a future token
+ * block ever needs `@media`/`@supports` nesting, this regex changes once here.
+ *
+ * Pure (no DOM, no fs) so the tsup ESM+CJS build of the vite plugin can import
+ * it safely.
+ *
+ * Consumer-facing implication: components must keep their `:global(:root)`
+ * blocks as flat literal declarations — no `@each` / SCSS loops — otherwise
+ * this parser sees zero tokens and the editor's alias picker / file-manager
+ * UI is empty for that component. See `src/components/Notification.svelte:86–92`
+ * for the documented reason a four-variant block stays expanded.
+ */
+export function extractGlobalRootBody(source: string): string {
+  const re = /:global\(:root\)\s*\{([^}]*)\}/g;
+  const bodies: string[] = [];
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(source)) !== null) {
+    bodies.push(m[1]);
+  }
+  return bodies.join('\n');
+}

package/src/lib/presetService.ts

@@ -0,0 +1,94 @@
+import type { Preset, PresetMeta, Theme, ComponentConfig } from './themeTypes';
+import { versionedFileResource } from './files/versionedFileResource';
+import { listComponents } from './componentConfigService';
+import { getActiveTheme } from './themeService';
+
+/**
+ * REST client for preset (bundle) manifest files. Each preset file references
+ * a theme file basename + a per-component config file basename. Loading a
+ * preset flips the corresponding `_active.json` pointers via `applyPreset`,
+ * leaving the underlying theme + component-config files as the source of
+ * truth.
+ *
+ * Mirrors the lifecycle of `themeService.ts` and `componentConfigService.ts`
+ * but adds one custom route — `PUT /api/presets/:name/apply` — that the
+ * server uses to atomically validate every reference and flip every pointer
+ * in one shot.
+ */
+
+const presetsResource = versionedFileResource<Preset, PresetMeta, never>({
+  baseUrl: '/api/presets',
+});
+
+export const listPresets = async (): Promise<PresetMeta[]> => {
+  const data = await presetsResource.list();
+  return data.files;
+};
+
+export const loadPreset = (fileName: string): Promise<Preset> =>
+  presetsResource.load(fileName);
+export const savePreset = (fileName: string, data: Preset): Promise<void> =>
+  presetsResource.save(fileName, data);
+export const deletePreset = (fileName: string): Promise<void> =>
+  presetsResource.remove(fileName);
+export const getActivePreset = (): Promise<Preset | null> => presetsResource.getActive();
+export const setActivePreset = (fileName: string): Promise<void> =>
+  presetsResource.setActive(fileName);
+
+export interface ApplyPresetResult {
+  ok: boolean;
+  preset: Preset;
+  theme: Theme;
+  componentConfigs: Record<string, ComponentConfig>;
+}
+
+/**
+ * Server-side atomic apply: validate every referenced file exists, flip the
+ * theme + each component's `_active.json` pointer, and return the resolved
+ * theme + component configs in one payload.
+ *
+ * The client typically follows this with a full page reload — loading a
+ * preset is a "blow up the world" action and preserving editor session
+ * state across that boundary is low value.
+ */
+export async function applyPreset(fileName: string): Promise<ApplyPresetResult> {
+  const res = await fetch(`/api/presets/${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();
+}
+
+/**
+ * Build a manifest from the *currently active files on disk* (not in-memory
+ * editor state) and persist it. Dirty editor state isn't a file yet, so it's
+ * not part of any preset until the user saves it. Callers should warn the
+ * user via the UI if `$dirty` is true before invoking this.
+ */
+export async function captureCurrentAsPreset(
+  fileName: string,
+  displayName: string,
+): Promise<void> {
+  const activeTheme = await getActiveTheme();
+  if (!activeTheme || !activeTheme._fileName) {
+    throw new Error('No active theme on disk to capture');
+  }
+  const components = await listComponents();
+  const componentConfigs: Record<string, string> = {};
+  for (const c of components) {
+    componentConfigs[c.name] = c.activeFile || 'default';
+  }
+  const now = new Date().toISOString();
+  const manifest: Preset = {
+    name: displayName,
+    createdAt: now,
+    updatedAt: now,
+    theme: activeTheme._fileName,
+    componentConfigs,
+  };
+  await savePreset(fileName, manifest);
+  await setActivePreset(fileName);
+}

package/src/lib/router.ts

@@ -0,0 +1,49 @@
+import { writable } from 'svelte/store';
+import { storageKey } from './editorConfig';
+
+function prevKey(): string {
+  return storageKey('prev-route');
+}
+
+function rememberPrev(current: string) {
+  if (current === '/editor') return;
+  try { sessionStorage.setItem(prevKey(), current); } catch { /* ignore */ }
+}
+
+export const route = writable<string>('/');
+
+let initialised = false;
+
+/**
+ * Idempotent host hook — call once during boot to seed the route store from
+ * the current location and wire popstate handling. Module import no longer
+ * touches `window`, so SSR / test harnesses can import without crashing.
+ */
+export function init(): void {
+  if (initialised) return;
+  initialised = true;
+  if (typeof window === 'undefined') return;
+  const initial = window.location.pathname || '/';
+  rememberPrev(initial);
+  route.set(initial);
+  window.addEventListener('popstate', () => {
+    route.set(window.location.pathname || '/');
+  });
+}
+
+/**
+ * Push a new history entry and update the route store. Produces exactly one
+ * `route` store update per call — the popstate listener installed in `init()`
+ * fires only on browser back/forward, not on synthetic dispatch.
+ */
+export function navigate(path: string) {
+  const [pathname] = path.split('#');
+  if (typeof window !== 'undefined') {
+    rememberPrev(window.location.pathname || '/');
+    history.pushState(null, '', path);
+    if (!path.includes('#')) {
+      window.scrollTo(0, 0);
+    }
+  }
+  route.set(pathname);
+}

package/src/lib/scrollSection.ts

@@ -0,0 +1,45 @@
+const PRELUDE_PX = 128;
+const DURATION_MS = 400;
+const SPEED_PX_PER_MS = PRELUDE_PX / DURATION_MS;
+
+function easeOutCubic(t: number): number {
+  return 1 - Math.pow(1 - t, 3);
+}
+
+function findScrollParent(el: HTMLElement): HTMLElement {
+  let node: HTMLElement | null = el.parentElement;
+  while (node) {
+    const style = getComputedStyle(node);
+    if (/(auto|scroll|overlay)/.test(style.overflowY) && node.scrollHeight > node.clientHeight) {
+      return node;
+    }
+    node = node.parentElement;
+  }
+  return document.scrollingElement as HTMLElement ?? document.documentElement;
+}
+
+export function scrollSectionIntoView(target: HTMLElement, scroller?: HTMLElement) {
+  const scrollEl = scroller ?? findScrollParent(target);
+  const max = scrollEl.scrollHeight - scrollEl.clientHeight;
+  const targetTop = Math.max(0, Math.min(max, target.offsetTop));
+  const start = scrollEl.scrollTop;
+  const delta = targetTop - start;
+  if (delta === 0) return;
+
+  const direction = delta > 0 ? 1 : -1;
+  const distance = Math.abs(delta);
+  const animatedDistance = Math.min(distance, PRELUDE_PX);
+  const duration = animatedDistance / SPEED_PX_PER_MS;
+
+  const animFrom = targetTop - animatedDistance * direction;
+  scrollEl.scrollTop = animFrom;
+
+  const t0 = performance.now();
+  function step(now: number) {
+    const t = Math.min(1, (now - t0) / duration);
+    scrollEl.scrollTop = animFrom + animatedDistance * direction * easeOutCubic(t);
+    if (t < 1) requestAnimationFrame(step);
+    else scrollEl.scrollTop = targetTop;
+  }
+  requestAnimationFrame(step);
+}

package/src/lib/slices/columns.ts

@@ -0,0 +1,59 @@
+/**
+ * Columns slice — fixed-shape (count/maxWidth/gutter/margin) state, derived to
+ * four CSS vars. Values default to a 12-column 1440px grid; while state matches
+ * the default we leave tokens.css in charge so the `clamp()` in
+ * `--columns-gutter` survives until the editor overrides it.
+ */
+import type { ColumnsState } from '../editorTypes';
+
+export const DEFAULT_COLUMNS: ColumnsState = { count: 12, maxWidth: 1440, gutter: 16, margin: 0 };
+
+export const COLUMN_VAR_NAMES = ['--columns-count', '--columns-max-width', '--columns-gutter', '--columns-margin'] as const;
+
+export function columnsToVars(c: ColumnsState): Record<string, string> {
+  return {
+    '--columns-count': String(c.count),
+    '--columns-max-width': `${c.maxWidth}px`,
+    '--columns-gutter': `${c.gutter}px`,
+    '--columns-margin': `${c.margin}px`,
+  };
+}
+
+/**
+ * Only emit column CSS vars once the user has actually modified columns.
+ * While columns match the default, we leave tokens.css in charge — which
+ * preserves the `clamp()` in `--columns-gutter` until the editor overrides it.
+ */
+export function columnsEqualsDefault(c: ColumnsState): boolean {
+  return c.count === DEFAULT_COLUMNS.count
+    && c.maxWidth === DEFAULT_COLUMNS.maxWidth
+    && c.gutter === DEFAULT_COLUMNS.gutter
+    && c.margin === DEFAULT_COLUMNS.margin;
+}
+
+export function parseColumnVars(vars: Record<string, string>): Partial<ColumnsState> {
+  const out: Partial<ColumnsState> = {};
+  const count = parseInt(vars['--columns-count'] ?? '', 10);
+  if (Number.isFinite(count) && count > 0) out.count = count;
+  const maxWidth = parseFloat(vars['--columns-max-width'] ?? '');
+  if (Number.isFinite(maxWidth)) out.maxWidth = Math.round(maxWidth);
+  const gutter = parseFloat(vars['--columns-gutter'] ?? '');
+  if (Number.isFinite(gutter)) out.gutter = Math.round(gutter);
+  const margin = parseFloat(vars['--columns-margin'] ?? '');
+  if (Number.isFinite(margin)) out.margin = Math.round(margin);
+  return out;
+}
+
+/**
+ * Loader: route the relevant entries from a freshly-loaded theme's vars bag
+ * into `next.columns` and remove them from the bag so derivation stays
+ * single-source. Mutates `next` and `rawVars` in place.
+ */
+export function loadColumnsFromVars(
+  next: import('../editorTypes').EditorState,
+  rawVars: Record<string, string>,
+): void {
+  const overrides = parseColumnVars(rawVars);
+  next.columns = { ...DEFAULT_COLUMNS, ...overrides };
+  for (const name of COLUMN_VAR_NAMES) delete rawVars[name];
+}

package/src/lib/slices/components.ts

@@ -0,0 +1,362 @@
+/**
+ * Components slice — per-component `{ activeFile, aliases, config, unlinked? }`.
+ *
+ * `aliases` are the typed component-token → semantic-token map (each entry is
+ * a `CssVarRef` discriminated union: `{ kind: 'token', name }` or
+ * `{ kind: 'literal', value }`). The renderer emits each alias entry as
+ * `var(<name>)` for tokens or as the raw literal for literals.
+ *
+ * `config` carries literal-valued knobs that don't follow the alias →
+ * `var(...)` shape (e.g. `--dialog-confirm-variant: 'primary'`). The set of
+ * keys routed to config lives in `componentConfigKeys`.
+ *
+ * Themes and components are orthogonal: `loadFromFile` preserves
+ * `state.components`.
+ *
+ * Sharing semantics: tokens with the same groupKey (registered explicitly
+ * via `registerComponentSchema`) are siblings. Each individual sibling can opt out of the group: `unlinked`
+ * lists the specific variable names that have detached, leaving the rest
+ * of the group intact. `setComponentAliasLinked` writes the alias to every
+ * sibling that is *currently linked* (i.e. not in `unlinked`) plus the
+ * target itself, re-joining it to the group; `unlinkComponentProperty`
+ * detaches just that one variable. The `unlinked` list persists across
+ * theme loads.
+ *
+ * Dirty tracking: `savedComponents` is the on-disk snapshot baseline (one
+ * stringified `{aliases, config}` bag per component). `componentDirty`
+ * re-evaluates on any state change or baseline bump. The baseline is set
+ * explicitly by the load path (`setSavedComponentBaseline`) — `loadComponentActive`
+ * and `seedComponentsFromApi` in editorStore call into this from their migration
+ * pipeline.
+ */
+import { writable, derived, get, type Readable } from 'svelte/store';
+import type { CssVarRef, EditorState } from '../editorTypes';
+import { store, mutate } from '../editorCore';
+
+const EMPTY_COMPONENT_BASELINE = JSON.stringify({ aliases: {}, config: {} });
+
+export function componentBaseline(slice: { aliases: Record<string, CssVarRef>; config: Record<string, unknown> }): string {
+  return JSON.stringify({ aliases: slice.aliases, config: slice.config });
+}
+
+export function componentsToVars(components: EditorState['components']): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const slice of Object.values(components)) {
+    for (const [varName, ref] of Object.entries(slice.aliases)) {
+      out[varName] = ref.kind === 'token' ? `var(${ref.name})` : ref.value;
+    }
+  }
+  return out;
+}
+
+export function getComponentOwnedVarNames(state: EditorState): string[] {
+  const names: string[] = [];
+  for (const slice of Object.values(state.components)) {
+    for (const name of Object.keys(slice.aliases)) names.push(name);
+  }
+  return names;
+}
+
+/**
+ * Loader: themes and components are orthogonal — component aliases live
+ * in their own files, not the theme JSON. Preserve the current slice
+ * across theme loads and strip any component-owned vars that may have
+ * leaked into the theme's cssVariables bag. Mutates `next` and `rawVars`
+ * in place.
+ */
+export function loadComponentsFromVars(
+  next: EditorState,
+  rawVars: Record<string, string>,
+): void {
+  next.components = structuredClone(get(store).components);
+  for (const name of getComponentOwnedVarNames(next)) delete rawVars[name];
+}
+
+// Module-private baseline for per-component dirty detection. Parallels
+// `savedAtIndex` + `historyTick` for the global flag; `componentSavedTick`
+// drives re-derivation when the baseline changes.
+const savedComponents: Record<string, string> = {};
+const componentSavedTick = writable(0);
+function bumpComponentSavedTick(): void { componentSavedTick.update((n) => n + 1); }
+
+export const componentDirty: Readable<Record<string, boolean>> = derived(
+  [store, componentSavedTick],
+  ([$state]) => {
+    const out: Record<string, boolean> = {};
+    for (const [comp, slice] of Object.entries($state.components)) {
+      out[comp] = componentBaseline(slice) !== (savedComponents[comp] ?? EMPTY_COMPONENT_BASELINE);
+    }
+    return out;
+  },
+);
+
+export function setComponentAlias(component: string, varName: string, ref: CssVarRef): void {
+  mutate(`set alias ${component}/${varName}`, (s) => {
+    const existing = s.components[component];
+    if (existing) {
+      existing.aliases[varName] = ref;
+    } else {
+      s.components[component] = { activeFile: 'default', aliases: { [varName]: ref }, config: {} };
+    }
+  });
+}
+
+export function clearComponentAlias(component: string, varName: string): void {
+  mutate(`clear alias ${component}/${varName}`, (s) => {
+    const slice = s.components[component];
+    if (!slice) return;
+    delete slice.aliases[varName];
+  });
+}
+
+export function setComponentConfig(component: string, key: string, value: unknown): void {
+  mutate(`set config ${component}/${key}`, (s) => {
+    const existing = s.components[component];
+    if (existing) {
+      existing.config[key] = value;
+    } else {
+      s.components[component] = { activeFile: 'default', aliases: {}, config: { [key]: value } };
+    }
+  });
+}
+
+export function clearComponentConfig(component: string, key: string): void {
+  mutate(`clear config ${component}/${key}`, (s) => {
+    const slice = s.components[component];
+    if (!slice) return;
+    delete slice.config[key];
+  });
+}
+
+function componentVarPrefix(component: string): string {
+  return `--${component}-`;
+}
+
+/**
+ * Per-component groupKey schema registered by editor modules. Maps each
+ * declared variable to its groupKey (the explicit sibling-set identifier).
+ * Tokens with the same groupKey are siblings; tokens not in the schema fall
+ * back to last-dash property inference so unmigrated editors keep working.
+ */
+const componentSchemas: Record<string, Map<string, string>> = {};
+/** Inverse of `componentSchemas`: groupKey → declared variables sharing it.
+ *  This is the linkage topology declared by the editor, independent of which
+ *  aliases the user happens to have saved. */
+const componentSchemaSiblings: Record<string, Map<string, string[]>> = {};
+
+const TYPOGRAPHY_PROP_SUFFIXES = ['font-family', 'font-size', 'font-weight', 'line-height'] as const;
+
+/** Pull the slot identifier off a typography variable name, e.g.
+ *  `--card-primary-title-font-family` → `'title'`. Returns null for
+ *  non-typography vars, where the slot concept doesn't apply. */
+function typographySlotOf(varName: string): string | null {
+  for (const suffix of TYPOGRAPHY_PROP_SUFFIXES) {
+    if (!varName.endsWith('-' + suffix)) continue;
+    const head = varName.slice(0, -(suffix.length + 1));
+    const lastDash = head.lastIndexOf('-');
+    if (lastDash < 0) return null;
+    return head.slice(lastDash + 1);
+  }
+  return null;
+}
+
+/**
+ * Register a component's token → groupKey mapping. Editors call this at
+ * module load (top of `<script>`) so sibling lookups can prefer explicit
+ * groupKeys over name-derived inference. Re-registration overwrites prior
+ * entries for the same component.
+ *
+ * Warns when a single groupKey covers typography variables whose name-derived
+ * slots differ — e.g. `groupKey: 'font-family'` covering both
+ * `--card-primary-title-font-family` and `--card-primary-body-font-family`.
+ * Slot prefixes (`title-font-family` vs `body-font-family`) are required so
+ * each slot is independently linkable. See `src/styles/CONVENTIONS.md`.
+ */
+export function registerComponentSchema(
+  component: string,
+  tokens: ReadonlyArray<{ variable: string; groupKey?: string }>,
+): void {
+  const map = new Map<string, string>();
+  const siblings = new Map<string, string[]>();
+  for (const t of tokens) {
+    if (!t.groupKey) continue;
+    map.set(t.variable, t.groupKey);
+    const list = siblings.get(t.groupKey) ?? [];
+    list.push(t.variable);
+    siblings.set(t.groupKey, list);
+  }
+  componentSchemas[component] = map;
+  componentSchemaSiblings[component] = siblings;
+
+  for (const [groupKey, vars] of siblings) {
+    const slots = new Set<string>();
+    for (const v of vars) {
+      const slot = typographySlotOf(v);
+      if (slot) slots.add(slot);
+    }
+    if (slots.size > 1) {
+      const slotList = [...slots];
+      const examples = slotList.map((s) => `"${s}-${groupKey}"`).join(', ');
+      console.warn(
+        `[registerComponentSchema] component "${component}" groupKey "${groupKey}" links typography variables with distinct slots: ${slotList.join(', ')}. ` +
+          `Use slot-prefixed groupKeys (e.g. ${examples}) so each slot is independently linkable.`,
+      );
+    }
+  }
+}
+
+/**
+ * Resolve a variable's groupKey from the component's registered schema.
+ * Returns null when the variable has no declared groupKey (i.e. it isn't a
+ * member of any sibling group).
+ */
+function getGroupKey(component: string, varName: string): string | null {
+  return componentSchemas[component]?.get(varName) ?? null;
+}
+
+/**
+ * Variables that share `varName`'s groupKey, i.e. are declared as one
+ * linkage group. The editor's registered schema is the source of truth — the
+ * declared topology is reported regardless of which aliases happen to be
+ * persisted in the slice, so link UI reflects the editor's intent rather than
+ * leaking through the on-disk state. Falls back to a slice scan only when the
+ * variable isn't declared (legacy/inferred groupKey).
+ */
+export function getComponentPropertySiblings(component: string, varName: string): string[] {
+  const groupKey = getGroupKey(component, varName);
+  if (!groupKey) return [];
+  const declared = componentSchemaSiblings[component]?.get(groupKey);
+  if (declared && declared.length > 0) return declared.slice();
+  const slice = get(store).components[component];
+  if (!slice) return [];
+  const siblings: string[] = [];
+  for (const v of Object.keys(slice.aliases)) {
+    if (getGroupKey(component, v) === groupKey) siblings.push(v);
+  }
+  return siblings;
+}
+
+function cssVarRefEqual(a: CssVarRef | undefined, b: CssVarRef | undefined): boolean {
+  if (!a || !b) return a === b;
+  if (a.kind !== b.kind) return false;
+  return a.kind === 'token'
+    ? a.name === (b as { kind: 'token'; name: string }).name
+    : a.value === (b as { kind: 'literal'; value: string }).value;
+}
+
+/** True iff `varName` is not individually opted out, has ≥2 declared siblings,
+ *  and the linked siblings agree — either all sharing the same explicit alias,
+ *  or all having no override (linked at the upstream default). */
+export function isComponentPropertyLinked(component: string, varName: string): boolean {
+  const slice = get(store).components[component];
+  if (slice?.unlinked?.includes(varName)) return false;
+  const siblings = getComponentPropertySiblings(component, varName);
+  if (siblings.length < 2) return false;
+  const unlinkedList = slice?.unlinked ?? [];
+  const linkedSiblings = siblings.filter((v) => !unlinkedList.includes(v));
+  if (linkedSiblings.length < 2) return false;
+  const aliases = slice?.aliases ?? {};
+  const first = aliases[linkedSiblings[0]];
+  return linkedSiblings.every((v) => cssVarRefEqual(aliases[v], first));
+}
+
+/** Write `ref` to `varName` and every sibling currently linked (not in `unlinked`),
+ *  and remove `varName` from the unlinked list so it rejoins the group. */
+export function setComponentAliasLinked(component: string, varName: string, ref: CssVarRef): void {
+  const groupKey = getGroupKey(component, varName);
+  const siblings = getComponentPropertySiblings(component, varName);
+  if (!groupKey || siblings.length === 0) {
+    setComponentAlias(component, varName, ref);
+    return;
+  }
+  mutate(`link ${component}/${groupKey}`, (s) => {
+    const slice = s.components[component] ?? (s.components[component] = { activeFile: 'default', aliases: {}, config: {} });
+    const unlinked = (slice.unlinked ?? []).filter((p) => p !== varName);
+    slice.aliases[varName] = ref;
+    for (const v of siblings) {
+      if (v === varName) continue;
+      if (!unlinked.includes(v)) slice.aliases[v] = ref;
+    }
+    if (unlinked.length === 0) delete slice.unlinked;
+    else slice.unlinked = unlinked;
+  });
+}
+
+/** Clear `varName` and every sibling currently linked (not in `unlinked`). */
+export function clearComponentAliasLinked(component: string, varName: string): void {
+  const groupKey = getGroupKey(component, varName);
+  const siblings = getComponentPropertySiblings(component, varName);
+  if (!groupKey || siblings.length === 0) {
+    clearComponentAlias(component, varName);
+    return;
+  }
+  mutate(`clear link ${component}/${groupKey}`, (s) => {
+    const slice = s.components[component];
+    if (!slice) return;
+    const unlinked = slice.unlinked ?? [];
+    for (const v of siblings) {
+      if (v === varName || !unlinked.includes(v)) delete slice.aliases[v];
+    }
+  });
+}
+
+/** Detach a single property from its sibling group. Other siblings stay linked
+ *  to each other; only `varName` becomes independently editable. */
+export function unlinkComponentProperty(component: string, varName: string): void {
+  const groupKey = getGroupKey(component, varName);
+  if (!groupKey) return;
+  const siblings = getComponentPropertySiblings(component, varName);
+  if (siblings.length < 2) return;
+  mutate(`unlink ${component}/${varName}`, (s) => {
+    const slice = s.components[component];
+    if (!slice) return;
+    const unlinked = slice.unlinked ?? [];
+    if (!unlinked.includes(varName)) {
+      slice.unlinked = [...unlinked, varName];
+    }
+  });
+}
+
+/** Rejoin `varName` to its sibling group as pure metadata: drop it from the
+ *  `unlinked` list without writing any alias. Use when the group has no
+ *  overrides yet (linked at the upstream default) and the user just wants to
+ *  re-engage membership — `setComponentAliasLinked` requires a ref to write,
+ *  which there is none of in that state. */
+export function relinkComponentProperty(component: string, varName: string): void {
+  const slice = get(store).components[component];
+  if (!slice?.unlinked?.includes(varName)) return;
+  mutate(`relink ${component}/${varName}`, (s) => {
+    const next = s.components[component];
+    if (!next?.unlinked) return;
+    const remaining = next.unlinked.filter((v) => v !== varName);
+    if (remaining.length === 0) delete next.unlinked;
+    else next.unlinked = remaining;
+  });
+}
+
+export function markComponentSaved(component: string): void {
+  const slice = get(store).components[component];
+  if (!slice) return;
+  savedComponents[component] = componentBaseline(slice);
+  bumpComponentSavedTick();
+}
+
+/**
+ * Set the on-disk baseline for a component without touching the store.
+ * Called by `loadComponentActive` / `seedComponentsFromApi` after their
+ * migration step so the post-load state reads clean.
+ */
+export function setSavedComponentBaseline(component: string, baseline: string): void {
+  savedComponents[component] = baseline;
+}
+
+/** Notify subscribers that the dirty baseline changed. */
+export function notifyComponentSavedChanged(): void {
+  bumpComponentSavedTick();
+}
+
+/** Test-only: clear the baseline and the dirty signal. */
+export function __resetComponentsForTests(): void {
+  for (const k of Object.keys(savedComponents)) delete savedComponents[k];
+  bumpComponentSavedTick();
+}