@motion-proto/live-tokens 0.65.1 → 0.67.0

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

@@ -2,9 +2,11 @@ import { derived, get, writable } from 'svelte/store';
 import {
   SKETCH_STYLES,
   DEFAULT_SKETCH_STYLE,
+  THEME_SKETCH_ID,
   hydrateSketchStyle,
   type SketchStyle,
 } from './sketchStyles';
+import { lookById, replaceRegisteredLooks, sketchLooks } from './sketchRegistry';
 import {
   applySketchLayer,
   hostRoot,
@@ -101,15 +103,21 @@ function readBaseline(): SketchStyle | null {
   return null;
 }
 
-/** 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:';
+/** Retired. Saved sketchstyles and shipped ones share one id namespace now, so
+    a file named `pencil` replaces the shipped Pencil rather than sitting beside
+    it. Stripped on read below; delete a release after that ships. */
+const RETIRED_USER_PREFIX = 'user:';
 
+/** Deliberately unvalidated. Looks are registered after this module is
+    imported, so an id it has never heard of is the normal case rather than a
+    fault: `selectSketchStyle` no-ops on one, and `sketchPick` already reports
+    a look nothing names as `adjusted`. Only a browser that has stored nothing
+    falls back. */
 function readStyleName(): string {
   try {
     const name = localStorage.getItem(STYLE_NAME_KEY);
-    if (name === '' || (name && (name in SKETCH_STYLES || name.startsWith(USER_STYLE_PREFIX)))) {
-      return name;
+    if (name !== null) {
+      return name.startsWith(RETIRED_USER_PREFIX) ? name.slice(RETIRED_USER_PREFIX.length) : name;
     }
   } catch {
     // fall through
@@ -122,8 +130,9 @@ function readStyleName(): string {
 export const sketchEnabled = writable<boolean>(readEnabled());
 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. */
+    keeps showing what the current look is closest to. Any id in the pool, or
+    `THEME_SKETCH_ID` for the look the open theme carries; empty only when
+    nothing was picked, or the picked file was deleted. */
 export const sketchStyleName = writable<string>(readStyleName());
 
 /** The settings as the selected sketchstyle defined them. Kept beside the live
@@ -134,7 +143,7 @@ export const sketchBaseline = writable<SketchStyle | null>(readBaseline());
 
 /** Dial-set fields only. `label` and `blurb` name the sketchstyle rather than
     describe the look, and no dial writes them. */
-function sameLook(a: SketchStyle, b: SketchStyle): boolean {
+export 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]);
@@ -170,9 +179,9 @@ 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. */
+    is what opening a theme means everywhere else (RJC 6). The name is recovered
+    over the whole pool, so a theme carrying a look a saved file also holds is
+    named by that file rather than falling back to `THEME_SKETCH_ID`. */
 export function openThemeSketchStyle(sketchStyle: SketchStyle | undefined): void {
   themeSketchStyle.set(sketchStyle);
   if (!sketchStyle) {
@@ -181,13 +190,56 @@ export function openThemeSketchStyle(sketchStyle: SketchStyle | undefined): void
     sketchStyleName.set('');
     return;
   }
-  const matched = (Object.keys(SKETCH_STYLES) as string[]).find((name) => sameLook(SKETCH_STYLES[name], sketchStyle));
+  const matched = get(sketchLooks).find((look) => sameLook(look.settings, sketchStyle))?.id;
   sketchSettings.set({ ...sketchStyle });
   sketchBaseline.set({ ...sketchStyle });
-  sketchStyleName.set(matched ?? '');
+  sketchStyleName.set(matched ?? THEME_SKETCH_ID);
   sketchEnabled.set(true);
 }
 
+/**
+ * Take the sketchstyle a theme carries as this browser's own, unless this
+ * browser has already decided for itself.
+ *
+ * The rule boot has always followed in dev, and the only one a built site has:
+ * a visitor who picked a look, or picked None, keeps it, and `themeSketchStyle`
+ * still learns what the theme holds so the panel can call the difference
+ * unsaved. Both branches set it, so a picker can offer the theme's look as a
+ * row either way.
+ *
+ * Takes the raw field rather than a `SketchStyle`, and hydrates it here: a
+ * built site reads its theme JSON straight off disk with no dev server to run
+ * `normalizeTheme` over it first, so this is the only place a look stored under
+ * a retired dial name gets carried forward. Anything that is not an object is
+ * the absent case, which is off (invariant 3).
+ */
+export function seedSketchFromTheme(sketchStyle: unknown): void {
+  const style =
+    typeof sketchStyle === 'object' && sketchStyle !== null && !Array.isArray(sketchStyle)
+      ? hydrateSketchStyle(sketchStyle)
+      : undefined;
+  if (hasPersistedSketchState()) {
+    themeSketchStyle.set(style);
+    return;
+  }
+  openThemeSketchStyle(style);
+}
+
+/** Go back to the look the theme carries, after picking something else. The
+    theme's is the one look a picker can offer that this module did not ship, so
+    it needs a door of its own beside `selectSketchStyle`; `setSketch` gives the
+    two the same face. Silent when the theme carries none, the way
+    `selectSketchStyle` is for a name it does not know. */
+export function selectThemeSketchStyle(): void {
+  const style = get(themeSketchStyle);
+  if (!style) return;
+  markSketchTouched();
+  if (get(sketchEnabled)) liveMovedSinceBake.set(true);
+  sketchStyleName.set(THEME_SKETCH_ID);
+  sketchBaseline.set({ ...style });
+  sketchSettings.set({ ...style });
+}
+
 /** 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. */
@@ -201,14 +253,17 @@ export const sketchOffLook = derived(
   },
 );
 
-export function selectSketchStyle(name: string): void {
-  const style = SKETCH_STYLES[name];
-  if (!style) return;
+/** Takes any id in the pool: shipped, or registered from a file or a consumer.
+    Silent for an id nothing knows, the way it has always been for an unknown
+    shipped name. */
+export function selectSketchStyle(id: string): void {
+  const look = lookById(id);
+  if (!look) return;
   markSketchTouched();
   if (get(sketchEnabled)) liveMovedSinceBake.set(true);
-  sketchStyleName.set(name);
-  sketchBaseline.set({ ...style });
-  sketchSettings.set({ ...style });
+  sketchStyleName.set(id);
+  sketchBaseline.set({ ...look.settings });
+  sketchSettings.set({ ...look.settings });
 }
 
 /** Saved sketchstyles, listed from the data tree. Empty until
@@ -216,17 +271,22 @@ export function selectSketchStyle(name: string): void {
     the network. */
 export const savedSketchStyles = writable<SketchStyleMeta[]>([]);
 
+/** Lists the files and registers them in one gesture, so the editor's grid and
+    a built site's picker read the same pool. Loading every file to list them is
+    affordable: a sketchstyle is a few dozen numbers, and the alternative is a
+    grid that cannot paint a row until it is picked. */
 export async function refreshSavedSketchStyles(): Promise<void> {
-  savedSketchStyles.set(await listSketchStyles());
-}
-
-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);
+  const files = await listSketchStyles();
+  const loaded = await Promise.all(files.map((f) => loadSketchStyle(f.fileName)));
+  savedSketchStyles.set(files);
+  replaceRegisteredLooks(
+    files.map((file, i) => ({
+      id: file.fileName,
+      label: file.name || file.fileName,
+      settings: loaded[i].settings,
+      source: file.isPackage ? ('shipped' as const) : ('file' as const),
+    })),
+  );
 }
 
 /** Writes whatever the dials currently say to a named file and selects it, so
@@ -243,15 +303,34 @@ export async function saveCurrentSketchStyle(name: string): Promise<string> {
   await refreshSavedSketchStyles();
   sketchSettings.set(settings);
   sketchBaseline.set({ ...settings });
-  sketchStyleName.set(USER_STYLE_PREFIX + fileName);
+  sketchStyleName.set(fileName);
   return fileName;
 }
 
+/** Overwrite the selected saved sketchstyle. The file name comes from the
+    selection rather than from re-slugifying the label, because the two can
+    disagree: a file hand-edited to a new display name would otherwise be saved
+    beside itself under a fresh slug instead of over itself. The label comes
+    from the look for the same reason, so the name the grid shows survives.
+
+    No `markSketchTouched`: the button only lights once a dial has moved, and
+    every dial goes through `updateSketchSettings`, which marks it. */
+export async function saveSelectedSketchStyle(): Promise<void> {
+  const look = lookById(get(sketchStyleName));
+  if (look?.source !== 'file') throw new Error('No saved sketchstyle is selected');
+  const settings = { ...get(sketchSettings) };
+  await saveSketchStyle(look.id, look.label, settings);
+  await refreshSavedSketchStyles();
+  // Re-baselining is what disables the button again and returns the readout
+  // from "Modified from X" to the saved blurb.
+  sketchBaseline.set(settings);
+}
+
 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) {
+  if (get(sketchStyleName) === fileName) {
     sketchStyleName.set('');
     sketchBaseline.set(null);
   }

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

@@ -12,6 +12,9 @@ export interface SketchStyleMeta {
   name: string;
   fileName: string;
   updatedAt: string;
+  /** Served from the package rather than this project, so there is no local
+      file to write over or delete. Saving over one creates that file. */
+  isPackage: boolean;
 }
 
 const BASE = `${API_BASE}/sketch-styles`;

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

@@ -1,3 +1,11 @@
+import pencil from '../../../live-tokens/data/sketch-styles/pencil.json';
+import marker from '../../../live-tokens/data/sketch-styles/marker.json';
+import whiteboard from '../../../live-tokens/data/sketch-styles/whiteboard.json';
+import hatched from '../../../live-tokens/data/sketch-styles/hatched.json';
+import dashed from '../../../live-tokens/data/sketch-styles/dashed.json';
+import napkin from '../../../live-tokens/data/sketch-styles/napkin.json';
+import dry from '../../../live-tokens/data/sketch-styles/dry.json';
+
 export interface SketchStyle {
   label: string;
   blurb: string;
@@ -59,8 +67,22 @@ export interface SketchStyle {
   hatchInk: number;
   strokeStyle: 'solid' | 'dashed';
   maskOn: boolean;
-  /** Wavelength of the coverage noise, in page px. Small gives speckle, large gives broad patches. */
-  maskBlob: number;
+  /** Blob size of the coverage noise, in page px, across and down. Small gives
+      speckle, large gives broad patches. */
+  maskBlobX: number;
+  maskBlobY: number;
+  /** Which way the stretch runs, in degrees clockwise from level. Nothing at
+      all while the two blob sizes match, since a field the same in every
+      direction is the same field turned. The tile only meets itself at the
+      angles that land the page's axes back on whole cells, so the dial is
+      answered with the nearest of those. */
+  maskAngle: number;
+  /** Whether the two move together. Unlinked they part, and the field comes out
+      stretched: blobs wider than they are tall read as a wash dragged sideways,
+      the way ink pulled across a page does. Stored rather than inferred from
+      the pair matching, so a look that stretches to exactly square keeps its
+      dials apart. */
+  maskBlobLinked: boolean;
   /** Output levels on the coverage field, 0 to 1: the palest the fill gets and
       the densest. The whole field is squeezed into the gap, never cut at it, so
       0.4 to 1 is a fill that is never thinner than 40% ink and 0 to 0.8 one
@@ -119,103 +141,34 @@ export interface SketchStyle {
   iconMaskScale: number;
 }
 
-const base: SketchStyle = {
-  label: '', blurb: '',
-  fillTravel: 1.5, strokeTravel: 1.5, wobble: 45, roughness: 3,
-  borderWavelength: 1, waveform: 1,
-  strokeWidth: 1.5, doubleStroke: false, retraceOffset: 1.2, retracePass: 'copy',
-  fillStyle: 'solid', hatchInk: 0.4, strokeStyle: 'solid',
-  pressure: 0.25, pressureMod: 0.35, pooling: 1.2, strokeInk: 1,
-  maskOn: true, maskBlob: 100, maskOutputMin: 0.45, maskOutputMax: 1,
-  maskOctaves: 2, maskGrain: 'fractal', maskPosterize: 1, maskSoftness: 1.5,
-  jitterX: 2.5, jitterY: 2.5, jitterRot: 0.6, jitterScale: 0.035,
-  cornerSpread: 10, cornerTravel: 8,
-  iconTravel: 1.25, iconWavelength: 0.625, iconMaskOn: true, iconMaskScale: 1,
-};
-
-export const SKETCH_STYLES: Record<string, SketchStyle> = {
-  pencil: {
-    ...base, label: 'Pencil',
-    blurb: 'Two graphite passes on their own seeds, so the outline disagrees with itself the way a hand coming back round does. Tight grain, little else.',
-    fillTravel: 0.75, strokeTravel: 1.25, wobble: 30, roughness: 3, waveform: 1,
-    strokeWidth: 1.25, doubleStroke: true, retracePass: 'reseeded', retraceOffset: 1.5, strokeInk: 0.85,
-    maskBlob: 40, maskOutputMin: 0.62, maskOutputMax: 1, maskOctaves: 3, maskPosterize: 1, maskSoftness: 0,
-    jitterX: 1.5, jitterY: 1.5, jitterRot: 0.35, jitterScale: 0.022,
-    cornerSpread: 6, cornerTravel: 4.5,
-    pressure: 0.15, pressureMod: 0.3, pooling: 0, iconTravel: 0.75,
-  },
-
-  marker: {
-    ...base, label: 'Marker',
-    blurb: 'Broad translucent nib gone round twice on the same line, so the overlap darkens and the ink pools where it slows.',
-    fillTravel: 2, strokeTravel: 1.5, wobble: 56, waveform: 1.4, borderWavelength: 1.3,
-    strokeWidth: 4, doubleStroke: true, retracePass: 'copy', strokeInk: 0.52, retraceOffset: 2.2,
-    maskBlob: 115, maskOutputMin: 0.42, maskOutputMax: 1, maskOctaves: 3, maskPosterize: 4, maskSoftness: 4,
-    jitterX: 3, jitterY: 3, jitterRot: 0.8, jitterScale: 0.045,
-    cornerSpread: 10, cornerTravel: 8,
-    pressure: 0.2, pressureMod: 0.25, pooling: 2, iconTravel: 1.25, iconMaskScale: 4,
-  },
-
-  whiteboard: {
-    ...base, label: 'Whiteboard',
-    blurb: 'The fattest nib on glass. One long smooth undulation, and a veined mask that streaks the fill like a half-wiped board.',
-    fillTravel: 2.5, strokeTravel: 2.5, wobble: 90, roughness: 1, waveform: 1, borderWavelength: 1.5,
-    strokeWidth: 5.5, doubleStroke: true, retracePass: 'copy', strokeInk: 0.66, retraceOffset: 3,
-    maskGrain: 'turbulence', maskBlob: 180, maskOutputMin: 0.42, maskOutputMax: 1,
-    maskOctaves: 1, maskPosterize: 3, maskSoftness: 8,
-    jitterX: 4.5, jitterY: 4.5, jitterRot: 1.2, jitterScale: 0.07,
-    cornerSpread: 14, cornerTravel: 11,
-    pressure: 0.15, pressureMod: 0.15, pooling: 3.5, iconTravel: 1.75, iconMaskScale: 1.5,
-  },
-
-  hatched: {
-    ...base, label: 'Hatched',
-    blurb: 'An etching. The fill is angled shading, the outline a single hard-edged scratch that chatters along its length. No mask: the hatch is the texture.',
-    fillTravel: 1.25, strokeTravel: 1.5, wobble: 24, roughness: 3, waveform: 3,
-    strokeWidth: 1.5, fillStyle: 'hatched', hatchInk: 0.5, doubleStroke: false,
-    maskOn: false, iconMaskOn: false,
-    jitterX: 1.5, jitterY: 1.5, jitterRot: 0.4, jitterScale: 0.03,
-    cornerSpread: 6, cornerTravel: 6,
-    pressure: 0.3, pressureMod: 0.45, pooling: 0.8, iconTravel: 1.25, iconWavelength: 0.5,
-  },
-
-  dashed: {
-    ...base, label: 'Dashed',
-    blurb: 'A drafting outline. One slow drift along the ruler, broken into strokes, with jitter, mask and pressure all off. The clean pole.',
-    strokeStyle: 'dashed', strokeTravel: 1, fillTravel: 0.5, wobble: 120, roughness: 1, waveform: 1,
-    strokeWidth: 1.5, doubleStroke: false,
-    maskOn: false, iconMaskOn: false,
-    jitterX: 0, jitterY: 0, jitterRot: 0, jitterScale: 0,
-    cornerSpread: 4, cornerTravel: 3,
-    pressure: 0, pressureMod: 0, pooling: 0, iconTravel: 0,
-  },
-
-  napkin: {
-    ...base, label: 'Napkin',
-    blurb: 'Ballpoint in a hurry. Everything loose at once: a square wave sends every edge to full travel, and the second pass lands wherever it lands.',
-    fillTravel: 3, strokeTravel: 2.25, wobble: 50, roughness: 3, waveform: 2.5,
-    strokeWidth: 2.25, doubleStroke: true, retracePass: 'reseeded', retraceOffset: 4, strokeInk: 1,
-    maskBlob: 150, maskOutputMin: 0.43, maskOutputMax: 0.95, maskOctaves: 2, maskPosterize: 2, maskSoftness: 10,
-    jitterX: 6, jitterY: 6, jitterRot: 1.8, jitterScale: 0.1,
-    cornerSpread: 20, cornerTravel: 17,
-    pressure: 0.45, pressureMod: 0.6, pooling: 2.5, iconTravel: 2.25, iconMaskScale: 3.6,
-  },
+/**
+ * The shipped sketchstyles, read from the files the package distributes. The
+ * files are the source: a project shadows one by saving a sketchstyle under the
+ * same id, the editor restores a shipped look by deleting that file, and
+ * `themeFileApi` serves these as the read-only fallback behind the project's own
+ * directory. Editing a look here means editing its JSON, which is what the
+ * Sketchstyle view already writes.
+ *
+ * Each file carries every dial, so there is nothing to merge a default into.
+ * `sketchStyles.test.ts` pins that: the seven key sets have to match, and a dial
+ * added to `SketchStyle` has to reach all seven before the suite goes green.
+ *
+ * Order is picker order.
+ */
+const SHIPPED_FILES = { pencil, marker, whiteboard, hatched, dashed, napkin, dry };
 
-  dry: {
-    ...base, label: 'Dry marker',
-    blurb: 'Ink that ran out. One scratchy pass that breaks up along its length, over a fill the mask has worn nearly through in patches.',
-    fillTravel: 2.25, strokeTravel: 1.75, wobble: 50, waveform: 2, borderWavelength: 0.5,
-    strokeWidth: 3.5, doubleStroke: false, strokeInk: 0.4,
-    maskBlob: 150, maskOutputMin: 0.24, maskOutputMax: 0.91,
-    maskOctaves: 2, maskPosterize: 4, maskSoftness: 1.75,
-    jitterX: 5, jitterY: 5, jitterRot: 1.4, jitterScale: 0.08,
-    cornerSpread: 16, cornerTravel: 13,
-    pressure: 0.4, pressureMod: 0.8, pooling: 1.5, iconTravel: 1.75, iconMaskScale: 3.8,
-  },
-};
+export const SKETCH_STYLES: Record<string, SketchStyle> = Object.fromEntries(
+  Object.entries(SHIPPED_FILES).map(([id, file]) => [id, file.settings as unknown as SketchStyle]),
+);
 
 export const DEFAULT_SKETCH_STYLE = 'marker';
 
+/** The id of the look a theme carries, in the same id namespace as the shipped
+    sketchstyles so one picker row and one `setSketch` call cover both. Never a
+    key of `SKETCH_STYLES`: a shipped style claiming it would shadow the theme's
+    own look in every picker. `index.test.ts` pins that. */
+export const THEME_SKETCH_ID = 'theme';
+
 /** Reconciled against a full sketchstyle in both directions: a value stored before a
     control existed picks up the default, and a value stored for a control since
     retired is dropped. Without the drop, a stale key survives every spread and
@@ -233,6 +186,7 @@ export function hydrateSketchStyle(raw: unknown): SketchStyle {
   convertCutToLevels(stored as Record<string, unknown>, out);
   carryLevelsToOutput(stored as Record<string, unknown>, out);
   halveSwingDials(stored as Record<string, unknown>, out);
+  splitBlobAxes(stored as Record<string, unknown>, out);
   convertCyclesToWavelength(stored as Record<string, unknown>, out);
   convertIconTileToScale(stored as Record<string, unknown>, out);
   restoreDerivedRetrace(stored as Record<string, unknown>, out);
@@ -280,6 +234,16 @@ function convertCyclesToWavelength(stored: Record<string, unknown>, out: SketchS
   if (typeof layers === 'number') out.roughness = Math.min(3, Math.max(1, layers));
 }
 
+/** The blob size was one number for both axes. A look stored before the split
+    comes back square, with the two dials linked, which is the look it had. */
+function splitBlobAxes(stored: Record<string, unknown>, out: SketchStyle): void {
+  const blob = stored.maskBlob;
+  if (typeof blob !== 'number') return;
+  out.maskBlobX = blob;
+  out.maskBlobY = blob;
+  out.maskBlobLinked = true;
+}
+
 /** The icon mask tile used to be a px size, which is a unit the glyph it covers
     has no say in: 90px against a 16px icon put a whole glyph inside one patch
     of the field, so it came out either untouched or gone. It is a share of the
@@ -305,7 +269,10 @@ function convertTiledMask(stored: Record<string, unknown>, out: SketchStyle): vo
   const scale = stored.maskScale;
   if (typeof scale !== 'number') return;
   const freq = stored.maskFrequency;
-  if (typeof freq === 'number') out.maskBlob = Math.round(scale / (freq * LEGACY_TILE));
+  if (typeof freq === 'number') {
+    out.maskBlobX = Math.round(scale / (freq * LEGACY_TILE));
+    out.maskBlobY = out.maskBlobX;
+  }
   const soft = stored.maskSoftness;
   if (typeof soft === 'number') out.maskSoftness = Number(((soft * scale) / LEGACY_TILE).toFixed(1));
 }

package/src/editor/core/themes/themeInit.ts

@@ -5,7 +5,7 @@ import { loadFromFile, seedComponentsFromApi } from '../store/editorStore';
 import { getActiveComponentConfig, type ComponentSummary } from '../components/componentConfigService';
 import { safeFetch } from '../storage/storage';
 import { API_BASE } from '../storage/apiBase';
-import { hasPersistedSketchState, openThemeSketchStyle, themeSketchStyle } from '../sketch/sketchStore';
+import { seedSketchFromTheme } from '../sketch/sketchStore';
 
 interface ListComponentsDto {
   components: ComponentSummary[];
@@ -67,16 +67,7 @@ export async function initializeTheme(): Promise<void> {
   // A failed fetch is not "the theme carries no sketchstyle": treating null as
   // absent would tell the panel the look is off the theme, or hand a fresh
   // browser a blank buffer, over a fetch that will likely succeed next time.
-  if (active) {
-    if (hasPersistedSketchState()) {
-      // The buffer already painted on the first frame; boot only learns what
-      // the theme holds so unsaved dial work reads as unsaved rather than
-      // getting silently overwritten (that overwrite is what Apply is for).
-      themeSketchStyle.set(active.sketchStyle);
-    } else {
-      // Nothing was ever recorded in this browser: the theme's value becomes
-      // the live value, the same reconciliation opening a theme performs.
-      openThemeSketchStyle(active.sketchStyle);
-    }
-  }
+  // The same call a built site makes (`@motion-proto/live-tokens/sketch`), so
+  // one rule decides what a theme's sketchstyle means at boot in both.
+  if (active) seedSketchFromTheme(active.sketchStyle);
 }

package/src/editor/docs/content/sketch-mode.md

@@ -6,7 +6,7 @@ they are drawn with.
 
 It is an effect layer, not a set of token values. It never touches a token
 itself, so turning it off returns every component to exactly what its tokens
-already say. A production build never carries the drawing.
+already say.
 
 Open the **Sketchstyle** view in the editor and switch **Sketch mode** on. The effect
 applies to the page behind the editor as well as to the preview, so what you see
@@ -38,10 +38,22 @@ than just a name:
 - **Napkin.** Ballpoint in a hurry. Everything loose at once.
 - **Dry marker.** Ink that ran out. One scratchy pass over a mostly eaten fill.
 
-Pick one, then move whatever you like. **Save as sketchstyle…** keeps your
-dials under a name of your own, alongside the shipped seven, as a file under
-`src/live-tokens/data/sketch-styles/`. That is a different gesture from
-saving a theme; see "Where the settings live" below.
+All seven ship as files, one per look, under
+`src/live-tokens/data/sketch-styles/` in the package. There is no look that
+exists only as code, so every one of them can be read, copied and edited.
+
+Pick one, then move whatever you like. **Save As** keeps your dials under a name
+of your own, alongside the shipped seven, as a file under
+`src/live-tokens/data/sketch-styles/` in your project. **Save** writes them back
+over the sketchstyle you have selected, and lights as soon as the dials leave
+it. On one of your own it writes that file. On a shipped one it writes your
+project's own copy under the same name, which takes its place in the list;
+delete that copy and the shipped file behind it comes back. Both are a
+different gesture from saving a theme; see "Where the settings live" below.
+
+Your sketchstyles and the shipped ones are one list. A sketchstyle named after
+a shipped one replaces it, keeping its place in the list, so a project that
+wants its own Pencil saves one and every picker shows that one instead.
 
 ## The dials
 
@@ -50,8 +62,11 @@ saving a theme; see "Where the settings live" below.
   few pixels off or runs it through the pen again on its own seed.
 - **Fill.** Solid or hatched, how far the fill's edge travels, and how far each
   instance is offset, rotated and scaled from its neighbours. **Ink coverage**
-  thins the fill with a field of blotches: set their size and how many levels of
-  detail, then work the field as a levels control. The field always runs black
+  thins the fill with a field of blotches: set their size across and down and
+  how many levels of detail, then work the field as a levels control. The two
+  sizes move together under a chain; break it and the blotches stretch, which
+  reads as ink dragged along the axis you widened, and a **Rotation** dial joins
+  them to point that stretch anywhere you like. The field always runs black
   to white whatever the noise underneath. Steps flattens it into tones, and
   Output squeezes the whole of it into the range the ink covers, from how pale
   it gets at its thinnest to how dense at its fullest. Menus and tooltips are
@@ -81,14 +96,68 @@ change. The built-in **Motion Proto** theme is read-only, so Save
 is disabled there; use **Save As** to fold the dials into a theme of your
 own.
 
-**Save as sketchstyle…** in the **Sketchstyle** view is a different gesture. It
-writes a named sketchstyle to `src/live-tokens/data/sketch-styles/`, a look you
-can pick from any theme. It never touches the open theme, and it never marks
+**Save** and **Save As** in the **Sketchstyle** view are a different gesture.
+They write a named sketchstyle to `src/live-tokens/data/sketch-styles/`, a look
+you can pick from any theme. Neither touches the open theme, and neither marks
 the look off the theme.
 
-Sketch mode is a tool for looking at the page, not a layer the page can ship.
-The theme records the dials, but nothing bakes them: `tokens.generated.css`
-never sees them, and a production build has no sketch layer in it at all.
+## Shipping the layer
+
+The dev server reads the open theme and paints whatever it carries. A built site
+has no server to ask, so it hands the field over itself:
+
+```ts
+import { seedSketchFromTheme } from '@motion-proto/live-tokens/sketch';
+import theme from './live-tokens/data/themes/sketchy.json';
+
+seedSketchFromTheme(theme.sketchStyle);
+await bootLiveTokens(App, '#app');
+```
+
+Call it before mounting, so the look is up on the first frame. Pass the field
+raw. A theme written against older dial names is carried forward on the way in,
+the same reconciliation the dev server runs on every theme it reads.
+
+Nothing is baked. `tokens.generated.css` still holds token values only, and the
+layer stays JavaScript the page runs, because it builds an SVG filter bank
+rather than a set of custom properties.
+
+A visitor who has picked a look of their own keeps it, None included. The theme
+seeds a browser that has decided nothing and never overwrites one that has, so
+calling this on every boot is safe.
+
+### Your own sketchstyles
+
+The dev server lists the files in `sketch-styles/`. A built site has no server
+to ask, so it hands them over at boot, the way it hands over components:
+
+```ts
+const files = import.meta.glob<{ name?: string; settings: unknown }>(
+  './live-tokens/data/sketch-styles/*.json',
+  { eager: true, import: 'default' },
+);
+
+await bootLiveTokens(App, '#app', {
+  sketchLooks: Object.entries(files).map(([path, file]) => {
+    const id = path.split('/').pop()!.replace('.json', '');
+    return { id, label: file.name || id, settings: file.settings };
+  }),
+});
+```
+
+Projects made with `create` ship this already. The file's slug is the look's
+id, so a sketchstyle picked in the editor keeps working once the site is built.
+
+### Building a picker
+
+`sketchLooks` is every look on offer, shipped and your own, as a store. Give
+each row `setSketch(look.id)`, and add your own **None** row: off is a state of
+the effect rather than one of the looks.
+
+`themeSketchLook` is the theme's own look as one more row. It is null when the
+theme carries none, and null when what it carries is a look already in
+`sketchLooks`, since that row names it. Its id goes to `setSketch` like any
+other, so a visitor who wanders off the theme's look can come back to it.
 
 ## Drawing your own elements