@motion-proto/live-tokens 0.61.0 → 0.63.0

package/src/editor/core/sketch/sketchLayer.ts

@@ -1,7 +1,7 @@
 /**
  * Sketch effect layer.
  *
- * Builds an SVG filter bank and a stylesheet from one SketchSettings and
+ * Builds an SVG filter bank and a stylesheet from one SketchStyle and
  * injects both into every document cssVarSync tracks, so the host page behind
  * the overlay iframe gets the same effect the editor's preview shows.
  *
@@ -16,7 +16,7 @@
  */
 import { getSyncedDocuments } from '../cssVarSync';
 import { buildMaskUri, MASK_TILE } from './maskField';
-import type { SketchSettings } from './sketchPresets';
+import type { SketchStyle } from './sketchStyles';
 
 const DEFS_ATTR = 'data-sketch-defs';
 const STYLE_ATTR = 'data-sketch-style';
@@ -84,6 +84,12 @@ interface PartSpec {
       drawn corner radii on the host instead, so the clip at least turns the
       same way the ink does. */
   clips?: boolean;
+  /** Keeps the ink coverage mask off the fill. Coverage wears a fill through in
+      patches, and a part that floats over arbitrary page content shows whatever
+      is behind it through the worn places: it stops reading as a surface the
+      pointer can land on. Set it where the part floats over the page rather
+      than over a scrim of its own. */
+  unmasked?: boolean;
   positioned?: boolean;
   strokeless?: boolean;
 }
@@ -165,7 +171,7 @@ const PART_SPECS: readonly PartSpec[] = [
     clips: true,
   },
   // The arrow is the tooltip's own ::after, so the box takes the fill only.
-  { sel: '.tooltip', stem: 'tooltip', positioned: true, strokeless: true },
+  { sel: '.tooltip', stem: 'tooltip', positioned: true, strokeless: true, unmasked: true },
 
   // Status blocks
   ...STATUS_VARIANTS.map((v) => ({ sel: `.callout-${v}`, stem: `callout-${v}` })),
@@ -189,6 +195,7 @@ const PART_SPECS: readonly PartSpec[] = [
     stroke: 'var(--menuselect-menu-border)',
     radius: 'var(--menuselect-menu-radius, 0px)',
     shadow: 'var(--menuselect-menu-shadow, none)',
+    unmasked: true,
   },
   { sel: '.tab', stem: 'tabbar-default', radius: 'var(--tabbar-default-tab-top-radius, 0px)' },
   { sel: '.tab.active', stem: 'tabbar-active', radius: 'var(--tabbar-active-tab-top-radius, 0px)' },
@@ -316,8 +323,9 @@ const FLOW_PARTS = PART_SPECS.filter((p) => !p.positioned).map((p) => p.sel).joi
 const STROKE_PARTS = PART_SPECS.filter((p) => !p.strokeless).map((p) => p.sel).join(', ');
 const UNCLIPPED = PART_SPECS.filter((p) => !p.clips).map((p) => p.sel).join(', ');
 const CLIPPED = PART_SPECS.filter((p) => p.clips).map((p) => p.sel).join(', ');
+const UNMASKED = PART_SPECS.filter((p) => p.unmasked).map((p) => p.sel).join(', ');
 
-export function buildDefsMarkup(s: SketchSettings): string {
+export function buildDefsMarkup(s: SketchStyle): string {
   /**
    * `warp` is the shape stage: one wave of noise whose wavelength spans a whole
    * component, so the four corners sample different parts of the field and the
@@ -576,7 +584,7 @@ const swing = (travel: number) => String(Number((travel * 2).toFixed(4)));
 /** Squares the displacement wave off around 0.5, its zero, so full amplitude is
     spent along the whole edge rather than only where the wave peaks. Both
     channels take it: the map reads x from R and y from G. */
-function squareOff(s: SketchSettings, from: string, to: string): string {
+function squareOff(s: SketchStyle, from: string, to: string): string {
   if (s.waveform <= 1) return '';
   const slope = s.waveform.toFixed(2);
   const intercept = ((1 - s.waveform) / 2).toFixed(3);
@@ -586,7 +594,7 @@ function squareOff(s: SketchSettings, from: string, to: string): string {
   `</feComponentTransfer>`;
 }
 
-const squaredResult = (s: SketchSettings, from: string, to: string) =>
+const squaredResult = (s: SketchStyle, from: string, to: string) =>
   (s.waveform > 1 ? to : from);
 
 /** Along-stroke pressure wavelength. Low, with a high floor in the transfer
@@ -642,7 +650,7 @@ const RETRACE_SEED = 53;
 const WARP_FREQUENCY = 0.08;
 
 
-export function buildStylesheet(s: SketchSettings): string {
+export function buildStylesheet(s: SketchStyle): string {
   const on = '[data-sketch]';
   const parts = `:is(${PARTS})`;
   const el = `${on} ${parts}`;
@@ -853,6 +861,10 @@ export function buildStylesheet(s: SketchSettings): string {
       `pointer-events:none;` +
     `}`;
 
+  /* The parts that float over page content take the fill whole, and everything
+     else the layer does with it. The second `:is` outweighs the rule above. */
+  const solidFills = s.maskOn ? `${el}:is(${UNMASKED})::before{mask-image:none;}` : '';
+
   // The hatch is laid over the fill as a second background LAYER rather than
   // as `background-image` beside a `background-color`, because a part is free
   // to name a gradient as its fill: the Kit's lead block hands the layer the
@@ -1037,7 +1049,7 @@ export function buildStylesheet(s: SketchSettings): string {
   }).join('');
 
   return [
-    registrations, vars, icons, host, fill, fillStyles, retrace, stroke,
+    registrations, vars, icons, host, fill, solidFills, fillStyles, retrace, stroke,
     seedRotation, shape, jitter, perPart, colours, states,
   ].join('\n');
 }
@@ -1071,12 +1083,21 @@ function defsNode(doc: Document): SVGSVGElement {
  * This only makes the effect *available*. An element opts in by carrying
  * data-sketch, which is what `setSketchScope` writes.
  */
-export function applySketchLayer(settings: SketchSettings): void {
+export function applySketchLayer(settings: SketchStyle): void {
   const defs = buildDefsMarkup(settings);
   const css = buildStylesheet(settings);
   for (const doc of getSyncedDocuments()) {
+    const style = styleNode(doc);
+    // Writing markup a document already has is a visible flash, not a no-op:
+    // rewriting defs destroys every filter the page is mid-paint against, and
+    // rewriting the sheet drops the mask image to be decoded again. Both are
+    // built from the same settings, so the sheet answers for the pair. The
+    // comparison is against the DOM rather than a variable because with the
+    // overlay open two instances of this module render into this page, and the
+    // document is the only ground they share.
+    if (style.textContent === css) continue;
     defsNode(doc).innerHTML = defs;
-    styleNode(doc).textContent = css;
+    style.textContent = css;
   }
 }
 
@@ -1094,7 +1115,7 @@ export function removeSketchLayer(): void {
  * The host page's root and the editor's own preview container are both scopes,
  * which is why this takes an element rather than assuming documentElement.
  */
-export function setSketchScope(el: HTMLElement | null, settings: SketchSettings | null): void {
+export function setSketchScope(el: HTMLElement | null, settings: SketchStyle | null): void {
   if (!el) return;
   if (!settings) {
     el.removeAttribute('data-sketch');

package/src/editor/core/sketch/sketchStore.ts

@@ -1,24 +1,71 @@
 import { derived, get, writable } from 'svelte/store';
 import {
-  SKETCH_PRESETS,
-  DEFAULT_SKETCH_PRESET,
-  hydrateSketchSettings,
-  type SketchSettings,
-} from './sketchPresets';
+  SKETCH_STYLES,
+  DEFAULT_SKETCH_STYLE,
+  hydrateSketchStyle,
+  type SketchStyle,
+} from './sketchStyles';
 import { applySketchLayer, hostRoot, removeSketchLayer, setSketchScope } from './sketchLayer';
+import { liveMovedSinceBake } from '../productionPulse';
 import {
-  deleteSketchPreset,
-  listSketchPresets,
-  loadSketchPreset,
-  saveSketchPreset,
-  slugifySketchPreset,
-  type SketchPresetMeta,
-} from './sketchPresetService';
+  deleteSketchStyle,
+  listSketchStyles,
+  loadSketchStyle,
+  saveSketchStyle,
+  slugifySketchStyle,
+  type SketchStyleMeta,
+} from './sketchStyleService';
 
 const ENABLED_KEY = 'lt.sketchEnabled';
 const SETTINGS_KEY = 'lt.sketchSettings';
-const PRESET_KEY = 'lt.sketchPreset';
+const STYLE_NAME_KEY = 'lt.sketchStyleName';
 const BASELINE_KEY = 'lt.sketchBaseline';
+/** Set only by a genuine user decision (`markSketchTouched`), never by the
+    `subscribe` write-back below. That write-back plants the four keys above
+    on every boot regardless of whether a dial was ever moved, so deriving
+    "touched" from their presence would answer "yes" from the second load
+    onward — this key is the thing that actually distinguishes the two. */
+const TOUCHED_KEY = 'lt.sketchTouched';
+
+/** True once this browser has recorded a genuine sketch decision, so boot
+    (`themeInit.ts`) can tell "never touched" from "explicitly off" and only
+    seed the live buffer from the theme in the first case. Mutated in place
+    by `markSketchTouched`; the first read migrates a browser that already
+    held real dial state before this key existed (RJC 7) so it starts
+    touched, not one this module is about to seed for the first time. */
+let sketchTouched = (() => {
+  try {
+    const recorded = localStorage.getItem(TOUCHED_KEY);
+    if (recorded !== null) return recorded === 'true';
+    const priorUse = localStorage.getItem(ENABLED_KEY) !== null || localStorage.getItem(SETTINGS_KEY) !== null;
+    localStorage.setItem(TOUCHED_KEY, String(priorUse));
+    return priorUse;
+  } catch {
+    return false;
+  }
+})();
+
+/** Reads `TOUCHED_KEY` fresh rather than the cached `sketchTouched`, because a
+    peer document's write lands in localStorage between this module's import
+    and a caller's await (`themeInit.ts`'s boot reconcile is exactly that
+    gap): the cache would still answer as it did at import time. */
+export function hasPersistedSketchState(): boolean {
+  try {
+    return localStorage.getItem(TOUCHED_KEY) === 'true';
+  } catch {
+    return false;
+  }
+}
+
+/** Called from every control a user can act on: a dial, a sketchstyle pick, the
+    on/off switch. Never from `openThemeSketchStyle` or the storage-sync `adopt`
+    path, both of which write the same four keys as a side effect of state
+    this browser did not decide on its own. */
+function markSketchTouched(): void {
+  if (sketchTouched) return;
+  sketchTouched = true;
+  persist(TOUCHED_KEY, 'true');
+}
 
 function readEnabled(): boolean {
   try {
@@ -28,61 +75,61 @@ function readEnabled(): boolean {
   }
 }
 
-function readSettings(): SketchSettings {
+function readSettings(): SketchStyle {
   try {
     const raw = localStorage.getItem(SETTINGS_KEY);
-    if (raw) return hydrateSketchSettings(JSON.parse(raw));
+    if (raw) return hydrateSketchStyle(JSON.parse(raw));
   } catch {
-    // fall through to the default preset
+    // fall through to the default sketchstyle
   }
-  return { ...SKETCH_PRESETS[DEFAULT_SKETCH_PRESET] };
+  return { ...SKETCH_STYLES[DEFAULT_SKETCH_STYLE] };
 }
 
-function readBaseline(): SketchSettings | null {
+function readBaseline(): SketchStyle | null {
   try {
     const raw = localStorage.getItem(BASELINE_KEY);
-    if (raw) return hydrateSketchSettings(JSON.parse(raw));
+    if (raw) return hydrateSketchStyle(JSON.parse(raw));
   } catch {
     // fall through
   }
   return null;
 }
 
-/** Marks a saved preset in `sketchPreset`, so a user file named `pencil` and
-    the shipped `pencil` stay distinguishable in one string. */
-export const USER_PRESET_PREFIX = 'user:';
+/** Marks a saved sketchstyle in `sketchStyleName`, so a user file named `pencil`
+    and the shipped `pencil` stay distinguishable in one string. */
+export const USER_STYLE_PREFIX = 'user:';
 
-function readPresetName(): string {
+function readStyleName(): string {
   try {
-    const name = localStorage.getItem(PRESET_KEY);
-    if (name === '' || (name && (name in SKETCH_PRESETS || name.startsWith(USER_PRESET_PREFIX)))) {
+    const name = localStorage.getItem(STYLE_NAME_KEY);
+    if (name === '' || (name && (name in SKETCH_STYLES || name.startsWith(USER_STYLE_PREFIX)))) {
       return name;
     }
   } catch {
     // fall through
   }
-  return DEFAULT_SKETCH_PRESET;
+  return DEFAULT_SKETCH_STYLE;
 }
 
-/** Off by default: the effect is a draft look, never something a project
-    inherits without asking for it. */
+/** Off by default: the effect paints nothing until the open theme's own
+    sketchstyle, or a decision this browser already recorded, says otherwise. */
 export const sketchEnabled = writable<boolean>(readEnabled());
-export const sketchSettings = writable<SketchSettings>(readSettings());
-/** The preset the dials started from. It survives dial moves, so the grid keeps
-    showing what the current look is closest to; empty only when nothing was
-    picked, or the picked file was deleted. */
-export const sketchPreset = writable<string>(readPresetName());
+export const sketchSettings = writable<SketchStyle>(readSettings());
+/** The sketchstyle the dials started from. It survives dial moves, so the grid
+    keeps showing what the current look is closest to; empty only when nothing
+    was picked, or the picked file was deleted. */
+export const sketchStyleName = writable<string>(readStyleName());
 
-/** The settings as the selected preset defined them. Kept beside the live
+/** The settings as the selected sketchstyle defined them. Kept beside the live
     settings so "modified" is derived by comparison rather than tracked as a
     flag: dial a value back to where it started and the tab stops claiming a
     change, with no bookkeeping to get wrong. */
-export const sketchBaseline = writable<SketchSettings | null>(readBaseline());
+export const sketchBaseline = writable<SketchStyle | null>(readBaseline());
 
-/** Dial-set fields only. `label` and `blurb` name the preset rather than
+/** Dial-set fields only. `label` and `blurb` name the sketchstyle rather than
     describe the look, and no dial writes them. */
-function sameLook(a: SketchSettings, b: SketchSettings): boolean {
-  return (Object.keys(a) as (keyof SketchSettings)[])
+function sameLook(a: SketchStyle, b: SketchStyle): boolean {
+  return (Object.keys(a) as (keyof SketchStyle)[])
     .filter((k) => k !== 'label' && k !== 'blurb')
     .every((k) => a[k] === b[k]);
 }
@@ -94,60 +141,122 @@ export const sketchDirty = derived(
 
 export const sketchBlurb = derived(sketchSettings, (s) => s.blurb);
 
-export function selectSketchPreset(name: string): void {
-  const preset = SKETCH_PRESETS[name];
-  if (!preset) return;
-  sketchPreset.set(name);
-  sketchBaseline.set({ ...preset });
-  sketchSettings.set({ ...preset });
+/** The live look as a theme would carry it: the dials when the effect is
+    on, nothing when it is off (RJC 1). A copy, not the store's own object,
+    so a caller holding onto the result can never observe a later dial move
+    through it. */
+export function liveSketchStyle(): SketchStyle | undefined {
+  return get(sketchEnabled) ? { ...get(sketchSettings) } : undefined;
 }
 
-/** Saved presets, listed from the data tree. Empty until `refreshUserPresets`
-    runs, so importing this module never reaches for the network. */
-export const userSketchPresets = writable<SketchPresetMeta[]>([]);
+/** The Sketchstyle view's on/off switch goes through here rather than a bare
+    `sketchEnabled.set`, so flipping it by hand marks this browser as having
+    made a sketch decision the same as any other control does. */
+export function setSketchEnabled(enabled: boolean): void {
+  markSketchTouched();
+  if (enabled !== get(sketchEnabled)) liveMovedSinceBake.set(true);
+  sketchEnabled.set(enabled);
+}
+
+/** What the open theme holds, so "unsaved" is a comparison rather than a
+    flag (RJC 5). Set by every path that opens or saves a theme. */
+export const themeSketchStyle = writable<SketchStyle | undefined>(undefined);
+
+/** Open a theme's sketchstyle: the dials, the on/off state, and the name
+    recovered by comparison (RJC 3). Overwrites the live buffer, which
+    is what opening a theme means everywhere else (RJC 6). Never writes a
+    `user:` name here: a saved sketchstyle is a file this look may not have come
+    from, and the only thing that can name one is picking it. */
+export function openThemeSketchStyle(sketchStyle: SketchStyle | undefined): void {
+  themeSketchStyle.set(sketchStyle);
+  if (!sketchStyle) {
+    sketchEnabled.set(false);
+    sketchBaseline.set(null);
+    sketchStyleName.set('');
+    return;
+  }
+  const matched = (Object.keys(SKETCH_STYLES) as string[]).find((name) => sameLook(SKETCH_STYLES[name], sketchStyle));
+  sketchSettings.set({ ...sketchStyle });
+  sketchBaseline.set({ ...sketchStyle });
+  sketchStyleName.set(matched ?? '');
+  sketchEnabled.set(true);
+}
 
-export async function refreshUserPresets(): Promise<void> {
-  userSketchPresets.set(await listSketchPresets());
+/** The live sketch differs from what the open theme carries. Presence is
+    half the comparison: on with dials the theme does not hold, or off while
+    the theme holds a layer, are both off the theme. */
+export const sketchOffLook = derived(
+  [sketchEnabled, sketchSettings, themeSketchStyle],
+  ([enabled, settings, saved]) => {
+    const live = enabled ? settings : undefined;
+    if (!live && !saved) return false;
+    if (!live || !saved) return true;
+    return !sameLook(live, saved);
+  },
+);
+
+export function selectSketchStyle(name: string): void {
+  const style = SKETCH_STYLES[name];
+  if (!style) return;
+  markSketchTouched();
+  if (get(sketchEnabled)) liveMovedSinceBake.set(true);
+  sketchStyleName.set(name);
+  sketchBaseline.set({ ...style });
+  sketchSettings.set({ ...style });
+}
+
+/** Saved sketchstyles, listed from the data tree. Empty until
+    `refreshSavedSketchStyles` runs, so importing this module never reaches for
+    the network. */
+export const savedSketchStyles = writable<SketchStyleMeta[]>([]);
+
+export async function refreshSavedSketchStyles(): Promise<void> {
+  savedSketchStyles.set(await listSketchStyles());
 }
 
-export async function selectUserSketchPreset(fileName: string): Promise<void> {
-  const file = await loadSketchPreset(fileName);
-  sketchPreset.set(USER_PRESET_PREFIX + fileName);
+export async function selectSavedSketchStyle(fileName: string): Promise<void> {
+  const file = await loadSketchStyle(fileName);
+  markSketchTouched();
+  if (get(sketchEnabled)) liveMovedSinceBake.set(true);
+  sketchStyleName.set(USER_STYLE_PREFIX + fileName);
   sketchBaseline.set({ ...file.settings });
   sketchSettings.set(file.settings);
 }
 
 /** Writes whatever the dials currently say to a named file and selects it, so
     saving leaves the tab pointing at the thing that was just saved rather than
-    back on "Adjusted from a preset". Returns the file name it allocated. */
-export async function saveCurrentAsSketchPreset(name: string): Promise<string> {
+    back on "Adjusted from a sketchstyle". Returns the file name it allocated. */
+export async function saveCurrentSketchStyle(name: string): Promise<string> {
   const trimmed = name.trim();
-  if (!trimmed) throw new Error('A preset needs a name');
-  const fileName = slugifySketchPreset(trimmed);
+  if (!trimmed) throw new Error('A sketchstyle needs a name');
+  const fileName = slugifySketchStyle(trimmed);
   if (!fileName) throw new Error('That name has no letters or digits to make a file name from');
+  markSketchTouched();
   const settings = { ...get(sketchSettings), label: trimmed };
-  await saveSketchPreset(fileName, trimmed, settings);
-  await refreshUserPresets();
+  await saveSketchStyle(fileName, trimmed, settings);
+  await refreshSavedSketchStyles();
   sketchSettings.set(settings);
   sketchBaseline.set({ ...settings });
-  sketchPreset.set(USER_PRESET_PREFIX + fileName);
+  sketchStyleName.set(USER_STYLE_PREFIX + fileName);
   return fileName;
 }
 
-export async function deleteUserSketchPreset(fileName: string): Promise<void> {
-  await deleteSketchPreset(fileName);
-  await refreshUserPresets();
-  // The dials keep their values; only the label stops naming a file that exists.
-  if (get(sketchPreset) === USER_PRESET_PREFIX + fileName) {
-    sketchPreset.set('');
+export async function deleteSavedSketchStyle(fileName: string): Promise<void> {
+  await deleteSketchStyle(fileName);
+  await refreshSavedSketchStyles();
+  // The dials keep their values; only the name stops naming a file that exists.
+  if (get(sketchStyleName) === USER_STYLE_PREFIX + fileName) {
+    sketchStyleName.set('');
     sketchBaseline.set(null);
   }
 }
 
 /** Every dial goes through here. The selection deliberately survives: the grid
-    keeps naming the preset this look came from, and `sketchDirty` reports the
-    drift. Save writes a new preset rather than overwriting the base. */
-export function updateSketchSettings(patch: Partial<SketchSettings>): void {
+    keeps naming the sketchstyle this look came from, and `sketchDirty` reports
+    the drift. Save writes a new sketchstyle rather than overwriting the base. */
+export function updateSketchSettings(patch: Partial<SketchStyle>): void {
+  markSketchTouched();
+  if (get(sketchEnabled)) liveMovedSinceBake.set(true);
   sketchSettings.update((s) => ({ ...s, ...patch }));
 }
 
@@ -155,36 +264,152 @@ function persist(key: string, value: string): void {
   try {
     localStorage.setItem(key, value);
   } catch {
-    // Private-mode storage denial is not worth surfacing for a draft look.
+    // Private-mode storage denial is not worth surfacing for one browser's dials.
   }
 }
 
-if (typeof document !== 'undefined') {
-  let installed = false;
+/** The root the effect paints in this document, or null while this document is
+    showing an editor surface. Registered by LiveTokensRouter: a consumer can
+    relocate the editor routes, so the router is the only thing that knows
+    whether what is on screen is a page or the editor's own chrome. Null until
+    it says so, which is what keeps the editor from flashing the effect over
+    itself between import and first render. */
+let pageRoot: HTMLElement | null = null;
 
-  const render = (enabled: boolean, settings: SketchSettings) => {
-    if (!enabled) {
-      if (installed) removeSketchLayer();
-      installed = false;
-      return;
-    }
-    applySketchLayer(settings);
+let installed = false;
+
+function render(enabled: boolean, settings: SketchStyle): void {
+  if (typeof document === 'undefined') return;
+  if (!enabled) {
+    if (installed) removeSketchLayer();
+    installed = false;
+    return;
+  }
+  applySketchLayer(settings);
+  installed = true;
+  // The editor's own chrome must never pick the effect up. Two roots qualify:
+  // the host page behind the overlay iframe, and this document while it is
+  // showing a page. The preview container scopes itself.
+  setSketchScope(hostRoot(), settings);
+  setSketchScope(pageRoot, settings);
+}
+
+/** Paint one look on the two roots `render` owns, and on nothing else.
+
+    `render(false, ...)` reaches further: it clears every `[data-sketch]` in
+    the document. The scopes it takes with it belong to `$effect`s that paint
+    from the live stores, which a preview deliberately never ticks, so those
+    never come back. Previewing a theme carrying no sketchstyle left the
+    Sketchstyle view's own stage crisp for good, Cancel included. */
+function paintPreviewRoots(style: SketchStyle | undefined): void {
+  if (typeof document === 'undefined') return;
+  if (style) {
+    applySketchLayer(style);
     installed = true;
-    // The editor's own chrome must never pick the effect up, so only the host
-    // page's root becomes a scope here. The preview container scopes itself.
-    setSketchScope(hostRoot(), settings);
-  };
+  }
+  setSketchScope(hostRoot(), style ?? null);
+  setSketchScope(pageRoot, style ?? null);
+}
+
+/** Paint a sketchstyle for the Theme Picker preview, bypassing the live
+    buffer entirely: going through `sketchSettings`/`sketchEnabled` would
+    `share()` the previewed dials into localStorage and overwrite whatever
+    the user had live, which is right for Apply (RJC 6) but would destroy
+    unsaved work the moment the picker opened a row. The paint reaches the
+    host page across the iframe boundary the same way Apply's does; only the
+    store write and the persistence are skipped. Pass `undefined` for a theme
+    that carries no sketchstyle. */
+export function previewSketchStyle(style: SketchStyle | undefined): void {
+  paintPreviewRoots(style);
+}
+
+/** Undo a sketchstyle preview by repainting the live buffer, which the
+    preview never touched. Re-deriving from the current stores rather than a
+    scraped snapshot means it can't drift from what they actually hold by the
+    time the picker closes. */
+export function revertSketchStylePreview(): void {
+  if (get(sketchEnabled)) {
+    paintPreviewRoots(get(sketchSettings));
+    return;
+  }
+  // The one case with nodes to take down: a sketched preview over a crisp live
+  // state injected the sheet. `render`'s sweep is safe here because every
+  // component scope answers to `sketchEnabled`, which is false.
+  render(false, get(sketchSettings));
+}
+
+export function setSketchPageRoot(el: HTMLElement | null): void {
+  if (el === pageRoot) return;
+  setSketchScope(pageRoot, null);
+  pageRoot = el;
+  render(get(sketchEnabled), get(sketchSettings));
+}
+
+/**
+ * What this document last exchanged with the other one, per key: written by
+ * `share`, recorded by `adopt`.
+ *
+ * A document must never write back a value it adopted. Comparing against its
+ * own store is not enough, because the echo is not identical, it is LATE: a
+ * drag sends a value every frame, the far side adopts the first and writes it
+ * back, and by then this side is three frames along. It reads the echo, sees a
+ * value it does not hold, and adopts its own past — the handle jumps back under
+ * the cursor and the drag cannot move.
+ */
+const shared = new Map<string, string>();
+
+function share(key: string, value: string): void {
+  if (shared.get(key) === value) return;
+  shared.set(key, value);
+  persist(key, value);
+}
 
+function adopt(key: string, value: string): void {
+  shared.set(key, value);
+}
+
+if (typeof document !== 'undefined') {
   sketchEnabled.subscribe((enabled) => {
-    persist(ENABLED_KEY, String(enabled));
+    share(ENABLED_KEY, String(enabled));
     render(enabled, get(sketchSettings));
   });
 
   sketchSettings.subscribe((settings) => {
-    persist(SETTINGS_KEY, JSON.stringify(settings));
+    share(SETTINGS_KEY, JSON.stringify(settings));
     render(get(sketchEnabled), settings);
   });
 
-  sketchPreset.subscribe((name) => persist(PRESET_KEY, name));
-  sketchBaseline.subscribe((b) => persist(BASELINE_KEY, b ? JSON.stringify(b) : ''));
+  sketchStyleName.subscribe((name) => share(STYLE_NAME_KEY, name));
+  sketchBaseline.subscribe((b) => share(BASELINE_KEY, b ? JSON.stringify(b) : ''));
+
+  /* The overlay editor runs in an iframe, so the Sketchstyle view and a
+     control on the page are separate instances of this module. localStorage
+     is the ground they share: each adopts a value only when it differs from
+     what it holds, and records what it adopted so it never sends that value
+     back. */
+  window.addEventListener('storage', (event) => {
+    if (event.storageArea !== localStorage) return;
+    if (event.key === ENABLED_KEY) {
+      const next = event.newValue === 'true';
+      adopt(ENABLED_KEY, String(next));
+      if (next !== get(sketchEnabled)) sketchEnabled.set(next);
+    } else if (event.key === SETTINGS_KEY) {
+      if (event.newValue && event.newValue !== JSON.stringify(get(sketchSettings))) {
+        const next = readSettings();
+        adopt(SETTINGS_KEY, JSON.stringify(next));
+        sketchSettings.set(next);
+      }
+    } else if (event.key === STYLE_NAME_KEY) {
+      const next = readStyleName();
+      adopt(STYLE_NAME_KEY, next);
+      if (next !== get(sketchStyleName)) sketchStyleName.set(next);
+    } else if (event.key === BASELINE_KEY) {
+      const current = get(sketchBaseline);
+      if ((event.newValue || '') !== (current ? JSON.stringify(current) : '')) {
+        const next = readBaseline();
+        adopt(BASELINE_KEY, next ? JSON.stringify(next) : '');
+        sketchBaseline.set(next);
+      }
+    }
+  });
 }