@motion-proto/live-tokens 0.67.0 → 0.68.1

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

@@ -1,70 +1,78 @@
 import { derived, get, type Readable } from 'svelte/store';
 import { THEME_SKETCH_ID } from './sketchStyles';
-import { lookById, sketchLooks, type SketchLook } from './sketchRegistry';
+import { sketchStyleById, sketchStyles, type SketchStyle } from './sketchRegistry';
 import {
-  sameLook,
+  sameSketchStyle,
   selectSketchStyle,
-  selectThemeSketchStyle,
+  selectUnsavedSketchStyle,
   setSketchEnabled,
   sketchEnabled,
-  sketchStyleName,
-  themeSketchStyle,
+  selectedSketchStyleId,
+  themeSketchSettings,
 } from './sketchStore';
 
-export { sketchLooks, registerSketchLook } from './sketchRegistry';
-export type { SketchLook, SketchLookSource, RegisterSketchLookInput } from './sketchRegistry';
+export { sketchStyles, registerSketchStyle } from './sketchRegistry';
+export type { SketchStyle, SketchStyleSource, RegisterSketchStyleInput } from './sketchRegistry';
 
-/** A look as one picker row. The theme's own look is offered this way too, and
+/** A style as one picker row. The theme's own style is offered this way too, and
     it belongs to no pool entry, so the fields only a pool entry has are off. */
-export type SketchLookRow = Omit<SketchLook, 'settings' | 'source'>;
+export type SketchStyleRow = Omit<SketchStyle, 'settings' | 'source'>;
 
 /**
- * The look the open theme carries, as one more row for a picker: same shape as
- * a shipped look, and `setSketch` takes its id like any other. Null when the
- * theme carries no sketchstyle, and null when what it carries IS one of the
- * shipped looks, since that look's own row already names it.
+ * Sketch settings the open theme carries that no sketchstyle file holds, as one
+ * more row for a picker: same shape as a shipped sketchstyle, and `setSketch`
+ * takes its id like any other. Null when the theme carries no settings, and
+ * null when what it carries matches a sketchstyle, since that file's own row
+ * already names it.
  *
- * Without this row the theme's look is a one-way door: a visitor lands on it,
- * picks Pencil, and nothing can take them back. It is also the only thing that
- * can name that look, which no shipped label can do honestly. A theme tuned off
- * `marker` still carries the label "Marker", so a row built from the style's
- * own label would sit beside the shipped Marker claiming to be it.
+ * A theme embeds its sketch settings by value, so it can hold a set that
+ * belongs to no file: Save As is what turns one into a sketchstyle. Until then
+ * this is the only row that can offer it. Without it the settings are a one-way
+ * door, a visitor picks Pencil and nothing can take them back.
+ *
+ * Labelled "Unsaved" rather than by the settings' own label, which lies: a theme
+ * tuned off `marker` still carries the label "Marker", so a row built from it
+ * would sit beside the shipped Marker claiming to be it.
  */
-export const themeSketchLook: Readable<SketchLookRow | null> = derived(
-  [themeSketchStyle, sketchLooks],
-  ([style, looks]) => {
-    if (!style) return null;
-    if (looks.some((look) => sameLook(look.settings, style))) return null;
-    return { id: THEME_SKETCH_ID, label: 'Theme', blurb: 'The look this theme carries.' };
+export const unsavedSketchStyle: Readable<SketchStyleRow | null> = derived(
+  [themeSketchSettings, sketchStyles],
+  ([settings, styles]) => {
+    if (!settings) return null;
+    if (styles.some((style) => sameSketchStyle(style.settings, settings))) return null;
+    return {
+      id: THEME_SKETCH_ID,
+      label: 'Unsaved',
+      blurb: 'Sketch settings this theme carries that no sketchstyle holds.',
+    };
   },
 );
 
 /**
  * What the page is drawing with. Three states, not two: the effect can be on
- * under a look no shipped sketchstyle names — one saved to a file, or one a
+ * under a style no shipped sketchstyle names — one saved to a file, or one a
  * theme carried — and a picker that collapses that into `off` tells the
  * visitor the page is crisp while it is visibly drawn.
  *
- * A dial moved off a shipped look keeps naming it, which is `selectSketchStyle`'s
- * own rule: the pick says where the look came from, and `sketchDirty` says it
+ * A dial moved off a shipped style keeps naming it, which is `selectSketchStyle`'s
+ * own rule: the pick says where the style came from, and `sketchDirty` says it
  * has since drifted.
  */
 export type SketchPick =
   | { state: 'off' }
-  | { state: 'look'; look: SketchLookRow }
+  | { state: 'style'; style: SketchStyleRow }
   | { state: 'adjusted' };
 
 export const sketchPick: Readable<SketchPick> = derived(
-  [sketchEnabled, sketchStyleName, sketchLooks, themeSketchLook],
-  ([on, name, looks, themeLook]): SketchPick => {
+  [sketchEnabled, selectedSketchStyleId, sketchStyles, unsavedSketchStyle],
+  ([on, name, styles, unsaved]): SketchPick => {
     if (!on) return { state: 'off' };
-    const look = looks.find((l) => l.id === name) ?? (themeLook?.id === name ? themeLook : undefined);
-    return look ? { state: 'look', look: { id: look.id, label: look.label, blurb: look.blurb } } : { state: 'adjusted' };
+    const style = styles.find((s) => s.id === name) ?? (unsaved?.id === name ? unsaved : undefined);
+    return style ? { state: 'style', style: { id: style.id, label: style.label, blurb: style.blurb } } : { state: 'adjusted' };
   },
 );
 
 /**
- * Draw the page with one of the looks in the pool, or `null` for none.
+ * Draw the page with one of the styles in the pool, or `null` for none.
  *
  * The only supported way for a consumer to drive the effect. Reaching for
  * `applySketchLayer` instead paints a stylesheet the store does not know it
@@ -77,15 +85,15 @@ export function setSketch(id: string | null): void {
     return;
   }
   if (id === THEME_SKETCH_ID) {
-    if (!get(themeSketchStyle)) {
-      throw new Error('No theme sketchstyle to draw with. `themeSketchLook` is null unless a theme carries one.');
+    if (!get(themeSketchSettings)) {
+      throw new Error('No theme sketchstyle to draw with. `unsavedSketchStyle` is null unless a theme carries one.');
     }
-    selectThemeSketchStyle();
+    selectUnsavedSketchStyle();
     setSketchEnabled(true);
     return;
   }
-  if (!lookById(id)) {
-    throw new Error(`Unknown sketchstyle "${id}". Ids come from sketchLooks and themeSketchLook.`);
+  if (!sketchStyleById(id)) {
+    throw new Error(`Unknown sketchstyle "${id}". Ids come from sketchStyles and unsavedSketchStyle.`);
   }
   selectSketchStyle(id);
   setSketchEnabled(true);
@@ -106,22 +114,22 @@ export { hasPersistedSketchState } from './sketchStore';
  * already decided for itself.
  *
  * The route from a saved theme to a built page. Hand it the theme's
- * `sketchStyle` field, raw: a built site has no theme API, so it reads its own
+ * `sketchSettings` field, raw: a built site has no theme API, so it reads its own
  * theme JSON and this hydrates what it finds. Absent, `null`, or anything that
  * is not an object all mean the same thing, which is no sketch.
  *
  * Call it before mounting, the way dev boot does (`bootstrap.ts` awaits
- * `initializeTheme` first), so the look is up on the first frame rather than
+ * `initializeTheme` first), so the style is up on the first frame rather than
  * arriving over a crisp page.
  *
  * A visitor who has recorded a pick of their own keeps it, None included: this
  * seeds an undecided browser and never overwrites a decided one, so it is safe
- * to call on every boot. `themeSketchLook` is populated either way, so a picker
- * can offer the theme's look as a row whether or not this painted it.
+ * to call on every boot. `unsavedSketchStyle` is populated either way, so a picker
+ * can offer the theme's style as a row whether or not this painted it.
  */
 export { seedSketchFromTheme } from './sketchStore';
 
-/** The dial set a theme's `sketchStyle` field holds, for a consumer typing the
+/** The dial set a theme's `sketchSettings` field holds, for a consumer typing the
     value it pulled out of its own theme JSON. `seedSketchFromTheme` takes it
     raw, so nothing has to be cast to hand it over. */
-export type { SketchStyle } from './sketchStyles';
+export type { SketchStyleSettings } from './sketchStyles';

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

@@ -19,7 +19,7 @@
  * Everything is integer maths on a Float32Array with no DOM, so what a test
  * asserts is what the browser paints.
  */
-import type { SketchStyle } from './sketchStyles';
+import type { SketchStyleSettings } from './sketchStyles';
 
 /** Samples across the tile, on both axes. Fixed, whatever the blobs measure:
     the field is blobs and gradients, so the browser stretching the tile back to
@@ -69,7 +69,7 @@ export interface MaskLattice {
   angle: number;
 }
 
-export function maskLattice(s: SketchStyle): MaskLattice {
+export function maskLattice(s: SketchStyleSettings): MaskLattice {
   const ask = s.maskBlobX === s.maskBlobY ? 0 : s.maskAngle;
   const rad = ask * (Math.PI / 180);
   const cos = Math.cos(rad), sin = Math.sin(rad);
@@ -78,7 +78,7 @@ export function maskLattice(s: SketchStyle): MaskLattice {
   const vx = fit(dx, ask, (v) => turnOf(-v[1] * s.maskBlobY, v[0] * s.maskBlobX));
   let vy = fit(dy, ask, (v) => turnOf(v[0] * s.maskBlobX, v[1] * s.maskBlobY));
   // Two vectors along one line describe no tile at all. The turn of the first
-  // is the whole look, so the second is the one that gives way.
+  // fixes the tile, so the second is the one that gives way.
   if (vx[0] * vy[1] - vx[1] * vy[0] === 0) vy = [-vx[1], vx[0]];
   return {
     vx,
@@ -131,7 +131,7 @@ function fit(d: Vec, ask: number, turn: (v: Vec) => number): Vec {
  * fitted to it, which meant the dial could only reach the sizes that divide
  * 600: it said 250px and painted 300px, and there was nothing above that.
  */
-export function maskTile(s: SketchStyle): { w: number; h: number } {
+export function maskTile(s: SketchStyleSettings): { w: number; h: number } {
   const { w, h } = maskLattice(s);
   return { w, h };
 }
@@ -228,11 +228,11 @@ function makePerlin(seed: number): (x: number, y: number, w: Wrap) => number {
  * the one before, stretched onto its own measured range.
  *
  * `veined` folds each octave at zero before summing. The fold puts a crease
- * wherever the octave crossed zero, which is the marbled look; plain sum is
+ * wherever the octave crossed zero, which is the marbled effect; plain sum is
  * cloud.
  */
 function rawField(
-  s: SketchStyle, seed: number, raster: number, lattice: MaskLattice,
+  s: SketchStyleSettings, seed: number, raster: number, lattice: MaskLattice,
 ): Float32Array {
   const noise = makePerlin(seed);
   const veined = s.maskGrain === 'turbulence';
@@ -388,7 +388,7 @@ function boxPass(f: Float32Array, n: number, radius: number, stride: number): Fl
     all four; the levels, the posterising and the blur are one pass each. */
 let rawCache: { key: string; field: Float32Array } | null = null;
 
-function cachedRaw(s: SketchStyle, seed: number): Float32Array {
+function cachedRaw(s: SketchStyleSettings, seed: number): Float32Array {
   const lattice = maskLattice(s);
   // Keyed on the tile vectors rather than the blob sizes: most of the Scale
   // dial's travel paints the same lattice at another size, and the field is
@@ -407,7 +407,7 @@ function cachedRaw(s: SketchStyle, seed: number): Float32Array {
  * pass did.
  */
 export function buildMaskField(
-  s: SketchStyle, seed = 9, through?: MaskStage,
+  s: SketchStyleSettings, seed = 9, through?: MaskStage,
 ): { field: Float32Array; raster: number } {
   const raw = cachedRaw(s, seed);
   if (through === 'noise') return { field: raw, raster: RASTER };
@@ -544,7 +544,7 @@ const CACHE_MAX = 6;
 const cache = new Map<string, string>();
 
 /** The field as a `url(...)` for `mask-image`. */
-export function buildMaskUri(s: SketchStyle, seed = 9, through?: MaskStage): string {
+export function buildMaskUri(s: SketchStyleSettings, seed = 9, through?: MaskStage): string {
   const key = [...KEYS.map((k) => s[k]), seed, through ?? 'all'].join('|');
   const hit = cache.get(key);
   if (hit) return hit;

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

@@ -1,7 +1,7 @@
 /**
  * Sketch effect layer.
  *
- * Builds an SVG filter bank and a stylesheet from one SketchStyle and
+ * Builds an SVG filter bank and a stylesheet from one SketchStyleSettings 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, maskTile } from './maskField';
-import type { SketchStyle } from './sketchStyles';
+import type { SketchStyleSettings } from './sketchStyles';
 
 const DEFS_ATTR = 'data-sketch-defs';
 const STYLE_ATTR = 'data-sketch-style';
@@ -325,7 +325,7 @@ 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: SketchStyle): string {
+export function buildDefsMarkup(s: SketchStyleSettings): 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
@@ -559,7 +559,7 @@ const MASK_POS = ['0 0', '-137px -211px', '-311px -97px', '-73px -389px', '-419p
  * A hand holds a rough size and misses it by a bit each time, so half to full
  * is the shape of the error. The four land in a different order row to row.
  *
- * Added, never subtracted, because a hand-drawn look tends to sit on a theme
+ * Added, never subtracted, because a hand-drawn line tends to sit on a theme
  * whose corners are already tight: a coefficient set that swung both ways
  * spent half its range clamped at zero.
  */
@@ -584,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: SketchStyle, from: string, to: string): string {
+function squareOff(s: SketchStyleSettings, from: string, to: string): string {
   if (s.waveform <= 1) return '';
   const slope = s.waveform.toFixed(2);
   const intercept = ((1 - s.waveform) / 2).toFixed(3);
@@ -594,7 +594,7 @@ function squareOff(s: SketchStyle, from: string, to: string): string {
   `</feComponentTransfer>`;
 }
 
-const squaredResult = (s: SketchStyle, from: string, to: string) =>
+const squaredResult = (s: SketchStyleSettings, from: string, to: string) =>
   (s.waveform > 1 ? to : from);
 
 /** Along-stroke pressure wavelength. Low, with a high floor in the transfer
@@ -650,7 +650,7 @@ const RETRACE_SEED = 53;
 const WARP_FREQUENCY = 0.08;
 
 
-export function buildStylesheet(s: SketchStyle): string {
+export function buildStylesheet(s: SketchStyleSettings): string {
   const on = '[data-sketch]';
   const parts = `:is(${PARTS})`;
   const el = `${on} ${parts}`;
@@ -1089,7 +1089,7 @@ 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: SketchStyle): void {
+export function applySketchLayer(settings: SketchStyleSettings): void {
   const defs = buildDefsMarkup(settings);
   const css = buildStylesheet(settings);
   for (const doc of getSyncedDocuments()) {
@@ -1132,7 +1132,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: SketchStyle | null): void {
+export function setSketchScope(el: HTMLElement | null, settings: SketchStyleSettings | null): void {
   if (!el) return;
   if (!settings) {
     el.removeAttribute('data-sketch');

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

@@ -1,97 +1,97 @@
 import { derived, get, writable, type Readable } from 'svelte/store';
-import { SKETCH_STYLES, hydrateSketchStyle, type SketchStyle } from './sketchStyles';
+import { SHIPPED_SKETCH_SETTINGS, hydrateSketchSettings, type SketchStyleSettings } from './sketchStyles';
 
-/** Where a look came from, which is what decides the affordances on offer.
+/** Where a style came from, which is what decides the affordances on offer.
     `shipped` is served by the package: it has a file, but not one in this
     project, so there is nothing here to save over or delete until the editor
     writes a copy. `file` lives in this project's data tree, so the editor can
     save over it and delete it. `registered` was handed to `bootLiveTokens`, so
     it is real on a built site but owns no file the editor could touch. */
-export type SketchLookSource = 'shipped' | 'file' | 'registered';
+export type SketchStyleSource = 'shipped' | 'file' | 'registered';
 
-export interface SketchLook {
+export interface SketchStyle {
   /** What `setSketch` takes. A saved sketchstyle's file slug is its id, so a
-      look picked in dev keeps working once the site is built. */
+      style picked in dev keeps working once the site is built. */
   id: string;
   label: string;
   blurb: string;
-  settings: SketchStyle;
-  source: SketchLookSource;
+  settings: SketchStyleSettings;
+  source: SketchStyleSource;
 }
 
-export interface RegisterSketchLookInput {
+export interface RegisterSketchStyleInput {
   id: string;
   label: string;
   blurb?: string;
   settings: unknown;
-  /** Only `replaceRegisteredLooks` sets this. A listing carries the package's
+  /** Only `replaceRegisteredSketchStyles` sets this. A listing carries the package's
       own sketchstyles as well as the project's, and the two differ in what the
       editor may do to them, so the row's origin has to survive the trip. */
-  source?: SketchLookSource;
+  source?: SketchStyleSource;
 }
 
-const SHIPPED: ReadonlyMap<string, SketchLook> = new Map(
-  Object.entries(SKETCH_STYLES).map(([id, style]) => [
+const SHIPPED: ReadonlyMap<string, SketchStyle> = new Map(
+  Object.entries(SHIPPED_SKETCH_SETTINGS).map(([id, settings]) => [
     id,
-    { id, label: style.label, blurb: style.blurb, settings: style, source: 'shipped' as const },
+    { id, label: settings.label, blurb: settings.blurb, settings, source: 'shipped' as const },
   ]),
 );
 
-/** Seeded with the shipped looks, then written by `registerSketchLook`. A Map
+/** Seeded with the shipped styles, then written by `registerSketchStyle`. A Map
     because re-setting an existing key keeps its position, so a project's own
     `pencil` lands where the shipped Pencil sat rather than at the end of the
     grid. */
-const looks = writable(new Map(SHIPPED));
+const styles = writable(new Map(SHIPPED));
 
 /**
- * Every sketchstyle on offer: the shipped looks, plus whatever this project
+ * Every sketchstyle on offer: the shipped styles, plus whatever this project
  * registered over and beside them. A store rather than a constant, because
  * registration happens after this module is imported.
  *
  * A picker adds its own "None" row, since off is a state of the effect rather
- * than one of the looks. A theme's own look is not here either; `themeSketchLook`
+ * than one of the styles. A theme's own style is not here either; `unsavedSketchStyle`
  * carries that one row.
  */
-export const sketchLooks: Readable<SketchLook[]> = derived(looks, (m) => [...m.values()]);
+export const sketchStyles: Readable<SketchStyle[]> = derived(styles, (m) => [...m.values()]);
 
-export function lookById(id: string): SketchLook | undefined {
-  return get(looks).get(id);
+export function sketchStyleById(id: string): SketchStyle | undefined {
+  return get(styles).get(id);
 }
 
-function put(m: Map<string, SketchLook>, look: RegisterSketchLookInput, source: SketchLookSource) {
+function put(m: Map<string, SketchStyle>, style: RegisterSketchStyleInput, source: SketchStyleSource) {
   // Hydrated on the way in: a consumer hands over raw JSON it imported, so this
-  // is the only place a look stored under a retired dial name gets carried
+  // is the only place a style stored under a retired dial name gets carried
   // forward, the same job `seedSketchFromTheme` does for a theme.
-  const settings = hydrateSketchStyle(look.settings);
-  return m.set(look.id, {
-    id: look.id,
-    label: look.label,
-    blurb: look.blurb ?? settings.blurb ?? '',
+  const settings = hydrateSketchSettings(style.settings);
+  return m.set(style.id, {
+    id: style.id,
+    label: style.label,
+    blurb: style.blurb ?? settings.blurb ?? '',
     settings,
     source,
   });
 }
 
-export function registerSketchLook(look: RegisterSketchLookInput): void {
-  looks.update((m) => put(new Map(m), look, 'registered'));
+export function registerSketchStyle(style: RegisterSketchStyleInput): void {
+  styles.update((m) => put(new Map(m), style, 'registered'));
 }
 
 /** Ids the last file listing claimed. The sweep below removes these and nothing
-    else, so a look handed to `bootLiveTokens` survives the editor opening. */
+    else, so a style handed to `bootLiveTokens` survives the editor opening. */
 let fromFiles: string[] = [];
 
 /** The editor re-lists its files after every save and delete, so a file removed
-    on disk has to leave the pool too. A file that had shadowed a shipped look
+    on disk has to leave the pool too. A file that had shadowed a shipped style
     hands the id back on its way out. */
-export function replaceRegisteredLooks(next: RegisterSketchLookInput[]): void {
-  looks.update((m) => {
+export function replaceRegisteredSketchStyles(next: RegisterSketchStyleInput[]): void {
+  styles.update((m) => {
     const out = new Map(m);
     for (const id of fromFiles) {
       const shipped = SHIPPED.get(id);
       if (shipped) out.set(id, shipped);
       else out.delete(id);
     }
-    for (const look of next) put(out, look, look.source ?? 'file');
+    for (const style of next) put(out, style, style.source ?? 'file');
     return out;
   });
   fromFiles = next.map((l) => l.id);