@ethlete/cli 3.0.0-next.23 → 3.0.0-next.24

package/CHANGELOG.md

@@ -1,5 +1,53 @@
 # @ethlete/cli
 
+## 3.0.0-next.24
+
+### Minor Changes
+
+- A sketch's changed area gives one box per cluster of changed pixels; `et design shot --crop changed` writes one sheet per cluster, and Studio shows one enlarged crop per cluster.
+- `et design check` now fails with `CANONICAL-CLASS` when a Tailwind class in a design part has a shorter canonical form, for example `w-[420px]` that can be written as `w-2xl`.
+- `et design sketch merge` takes `--variant <key> --allowed-by <plan ref>`: it merges a sketch with no pick when that variant is its only live one, and logs the plan in `accepted.json`.
+- `et update` adds the packages a codemod requires, such as `ts-morph`, as dev dependencies before it runs the codemod, in a commit of its own. A migration declares them in its new `requires` field.
+- A design product can list stylesheets a command generates from a part (`generated`). A frame of a sketch variant that changes that part runs the command against the variant's part and loads its output.
+- `et design check` now fails a literal duration, delay or easing in a transition or animation outside `foundations/`, with `HARD-CODED-MOTION`.
+- `et design check` now fails an inline `<svg>` outside `foundations/`, with `INLINE-SVG`. A computed drawing passes with `data-et-drawing`.
+- `et design sketch merge` and `sketch discard` now resolve the addressed comments of the sketch, and a merge those of its parts without a sketch. New `et design comment resolve-ended` resolves the addressed comments of ended sketches.
+- `et design complete <layer>/<name>` fails while a part's declared `controls` lack drawn, reviewed evidence; it checks the `disclosure` kind first.
+- `et design complete` now discovers drawn controls: an unmarked native, ARIA or SDK control fails as `CONTROL-UNDECLARED`, a pointer or `:hover` element outside a control as `CONTROL-UNCLASSIFIED`, and `CONTROLS-MISSING` is gone.
+- `et design complete` now fails a control whose part draws its interactions as flat states instead of an `interactionRows` grid.
+- A page control in `definePart({ controls })` names the part that draws it in `part`; `et design complete` takes its interactions from that part and fails while that part is not design complete.
+- `et design complete` now requires a state that forces `active` on a control with `pointer` input, next to the state that forces `hover`.
+- `et design complete` now fails a control whose forced interaction changes a colour, background, border or shadow without a transition.
+- `et design check` fails with `CONTRAST` when drawn text is below WCAG 2 AA against its composited background. Parts declare token `pairs` to compute and `exceptions` with a reason; `contrastRatioOf` draws a ratio table.
+- A part's rules now run in its design frame. A switch morphs the existing DOM, so CSS transitions run, then plays the motion the rule names, with a controlled clock, seeded random and `from`-state measurements.
+- A design part can declare `motions` between its states, and a rule can name one. `et design check` fails on a motion between unknown states, a rule naming an undeclared motion, and `setTimeout` in motion code.
+- `et design check` now fails with `UTILITY-CSS` when a design part's CSS holds a declaration that a Tailwind utility of the product draws, for example `display: flex`.
+- `et design`: a product's `shared/` folder holds helper modules that are no part; any part imports them as `@shared/<path>`, and editing one marks each importing part changed.
+- The design server lists per sketch variant the states it adds and drops and its changed part note. Studio says on the canvas when a variant changes no pixel, and a click shows the old and new note.
+- `et design sketch new` takes several parts: one sketch, one variant folder holding them all, one `ready`, one merge; `ready` and `preview` name every part a `shared/` edit reaches; Studio shows every target part.
+
+### Patch Changes
+
+- `et update --continue` no longer commits what you changed after the stopped run, such as a package you installed by hand, into its own commits.
+- `et design check` no longer reports contrast for the label of a disabled control: a `label[for]`, a wrapping label, or an `aria-labelledby` target.
+- The design server's Studio event stream now also sends `calls` and `sketches` when a call or sketch file changes, and a `parts` event for a design system change that redraws no frame.
+- The design server draws up to four pictures at once instead of one, so cold shots, sketch lists and merge views render about three times faster. High-priority drawings still start before waiting low ones.
+- `et design` draws with partial raster off, so two draws of a page with embedded frames give the same picture under load, and `sketch ready` gives the same answer on a re-run.
+- The design auto-merge check now skips rejected variants, so only live variants can block a merge that is safe.
+- `et design` now fails with the frame URL when a frame or an embedded frame never draws, instead of saving a blank picture. `sketch ready` draws a changed state once more before it counts as a change.
+- Drawn design frames no longer show a real hover on a control at the frame's top-left corner, so `design shot` and `design complete` see only the interactions a state forces.
+- `et design` `CANONICAL-CLASS` and `UTILITY-CSS` now check the files of a `shared/` folder that a part imports, also in a sketch, so `sketch check` and `sketch ready` catch them before a merge.
+- Design screenshots now show the end of every finite CSS animation and transition, so an element that fades in with `@starting-style` is drawn fully visible.
+- The design server draws each shot on a warm browser page per viewport and scale instead of opening a new browser context, so a warm shot is about 12 % faster and a batch uses about 20 % less CPU.
+- The `et design` server now keeps the pixel compare of each sketch's unchanged states until a product file changes, so the sketch list loads in a fraction of the time after the first call.
+- `et design` redraws only the affected parts, not every part, when a file that a product stylesheet scans as a Tailwind `@source` changes.
+- `et design inbox done` now writes the note into the sketch variant for a comment on a part that exists only in the sketch, instead of failing with "is no part of".
+- A multi-target sketch merge gives each target only the `shared/` files it imports, directly or transitively; an unimported file returns to the target that held it. `sketch new` refuses targets whose `shared/` files clash.
+- `et design sketch ready` now also draws the parts that show the sketched part before it merges on its own. When one of them changes, the sketch stays ready and the output names the part and state.
+- A sketch with several targets shows the diff marks and the pages that use any target part. Studio names the parts a `shared/` edit reaches. The sketch-diff endpoint takes `part=`.
+- `et design` draws a sketch variant with its own part stylesheet where the product stylesheet `@import`s the merged one, so `sketch ready` no longer auto-merges a token value change as "no visible change".
+- A cold sketch shows its first frame sooner: Studio lists the sketches without the slow unchanged-state comparison first (`?unchanged=no`), asks for shots and diffs at once, then lists them in full.
+
 ## 3.0.0-next.23
 
 ### Minor Changes

package/design/contrast.ts

@@ -0,0 +1,49 @@
+type Rgba = [number, number, number, number];
+
+const rgbaIn = (probe: HTMLElement, value: string): Rgba => {
+  probe.style.color = `color-mix(in srgb, ${value} 100%, transparent)`;
+
+  const computed = getComputedStyle(probe).color;
+  const numbers = [...computed.matchAll(/-?[\d.]+(?:e-?\d+)?/g)].map((match) => parseFloat(match[0]));
+  const scale = computed.startsWith('color(') ? 1 : 255;
+  const [r = 0, g = 0, b = 0] = numbers.map((channel) => Math.min(1, Math.max(0, channel / scale)));
+
+  return [r, g, b, numbers[3] ?? 1];
+};
+
+const over = (top: Rgba, under: Rgba): Rgba => [
+  top[0] * top[3] + under[0] * (1 - top[3]),
+  top[1] * top[3] + under[1] * (1 - top[3]),
+  top[2] * top[3] + under[2] * (1 - top[3]),
+  1,
+];
+
+const luminanceOf = ([r, g, b]: Rgba) => {
+  const linear = (channel: number) => (channel <= 0.04045 ? channel / 12.92 : ((channel + 0.055) / 1.055) ** 2.4);
+
+  return 0.2126 * linear(r) + 0.7152 * linear(g) + 0.0722 * linear(b);
+};
+
+/**
+ * The WCAG 2 contrast ratio of the colour `text` on the colour `on`, both CSS colours resolved inside `within`
+ * (`document.body` by default), so `var(--token)` works. A translucent `on` is laid over the background of
+ * `document.body`. For a ratio table in a drawing's `setup`: `contrastRatioOf({ text: 'var(--text)', on: 'var(--surface)', within: root })`.
+ */
+export const contrastRatioOf = (options: { text: string; on: string; within?: Element }) => {
+  const probe = document.createElement('i');
+
+  probe.style.display = 'none';
+  (options.within ?? document.body).append(probe);
+
+  try {
+    const page = over(rgbaIn(probe, getComputedStyle(document.body).backgroundColor), [1, 1, 1, 1]);
+    const behind = over(rgbaIn(probe, options.on), page);
+    const [light, dark] = [luminanceOf(over(rgbaIn(probe, options.text), behind)), luminanceOf(behind)].sort(
+      (a, b) => b - a,
+    );
+
+    return ((light ?? 0) + 0.05) / ((dark ?? 0) + 0.05);
+  } finally {
+    probe.remove();
+  }
+};

package/design/define-call.ts

@@ -1,3 +1,5 @@
+import { morph } from './morph';
+
 /**
  * A value inside a template. An array joins with nothing between, and `null`, `undefined` and
  * `false` write nothing, so `${rows.map(row)}` and `${isOn && html`…`}` both read as they look.
@@ -81,7 +83,7 @@ export type StateRule<TState extends string> = { click: string; go: TState };
 
 /**
  * Swaps the content of the drawing's state host for `states[rule.go]` when a click matches a rule.
- * The first matching rule wins. The swap runs in a View Transition where the browser has one.
+ * The first matching rule wins. The swap morphs the existing DOM, so CSS transitions run.
  */
 export const switchStates =
   <TState extends string>(states: Record<TState, string>, rules: StateRule<TState>[]) =>
@@ -100,13 +102,8 @@ export const switchStates =
 
       if (!rule) return;
 
-      const swap = () => {
-        host.innerHTML = states[rule.go];
-        host.dataset['deStates'] = rule.go;
-      };
-
-      if (document.startViewTransition) document.startViewTransition(swap);
-      else swap();
+      morph(host, states[rule.go]);
+      host.dataset['deStates'] = rule.go;
     });
   };
 

package/design/define-part.ts

@@ -1,6 +1,7 @@
 import { Drawing } from './define-call';
 import { forceBody } from './mark-part';
 
+export { contrastRatioOf } from './contrast';
 export { css, drawing, html, ng } from './define-call';
 export type { Drawing } from './define-call';
 export { embedPage } from './embed-page';
@@ -23,9 +24,13 @@ export type Interaction = 'hover' | 'focus-visible' | 'active' | 'disabled';
  * component or element is drawn at the size of its content, and a page at every viewport preset.
  * `interactions` lists the interactions each state is also drawn in; without it only rest is drawn.
  * `grid` draws the states it names as one table in rest, see `StateGrid`.
+ * `controls` names each control the part draws, keyed by the id its markup carries in `data-et-control`; `design
+ * complete` requires the states and surfaces its `kind` and `input` need, see `Control`.
+ * `motions` names each motion between two of its states, see `Motion`; a rule in `rules` can name one.
  * `checks.skip` names the render checks of `design check` the part breaks on purpose, such as
  * `CLIPPED` for a part that cuts its content. To skip a check for one element only, put
  * `data-et-skip="CLIPPED"` on it; the check then ignores that element and everything inside it.
+ * `contrast` feeds the contrast check of `design check`, see `PartContrast`.
  */
 export type Part<TProps, TState extends string = string> = {
   note: string;
@@ -35,10 +40,37 @@ export type Part<TProps, TState extends string = string> = {
   widths?: number[];
   interactions?: Interaction[];
   grid?: StateGrid<TState>;
+  controls?: Record<string, Control<TState>>;
   checks?: { skip?: RenderCheck[] };
+  contrast?: PartContrast;
+  motions?: Record<string, Motion<TState>>;
+  rules?: PartRule<TState>[];
   render: (props: TProps, options?: RenderOptions) => DrawnPart | Promise<DrawnPart>;
 };
 
+/** What `play` of a motion may use, so Studio controls time: `at` schedules `fn` at `ms` into the motion on the tool's clock, `random` is seeded, `rect` measures a selector in the `from` state. */
+export type MotionContext = {
+  at: (ms: number, fn: () => void) => void;
+  random: () => number;
+  rect: (selector: string) => DOMRect;
+};
+
+/**
+ * A motion from the state `from` to the state `to`. `at` adds shot times in ms, `interrupt` starts the reverse motion
+ * at that time, `viewTransition` uses a View Transition, and `play` runs after the morph for what CSS cannot express.
+ */
+export type Motion<TState extends string = string> = {
+  from: TState;
+  to: TState;
+  at?: number[];
+  interrupt?: number;
+  viewTransition?: boolean;
+  play?: (ctx: MotionContext) => void;
+};
+
+/** A rule of a part: `on` an event on a selector, the part switches `to` a state, with the `motion` it names. */
+export type PartRule<TState extends string = string> = { on: string; to: TState; motion?: string };
+
 /** A drawing of a part: its `styles` hold the part's stylesheet and the ones `render` returned, so a host can add them up. */
 export type DrawnPart = Drawing & { styles: string };
 
@@ -51,17 +83,47 @@ export type StateGrid<TState extends string = string, TColumn extends string = s
   rows: Record<string, Partial<Record<TColumn, TState>>>;
 };
 
+/** How a control is operated: `pointer` requires a drawn hover, `keyboard` a drawn focus-visible. */
+export type ControlInput = 'pointer' | 'keyboard';
+
+/** A component or element part that draws a control and its interactions. */
+export type ControlPart = `components/${string}` | `elements/${string}`;
+
+/**
+ * A control `design complete` checks. A `disclosure` needs a state that draws it collapsed and the state its
+ * `surfaces.body` names, which draws the element marked `data-et-surface="<id>.body"` visible and filled.
+ * With `part`, the interactions come from that part, which must be design complete itself; a page control needs it.
+ * With `input`, a state of this part draws each required interaction, e.g. with `forceInteraction`.
+ */
+export type Control<TState extends string = string> = { kind: 'disclosure'; surfaces: { body: TState } } & (
+  { part: ControlPart; input?: never } | { input: ControlInput[]; part?: never }
+);
+
 /** A rule of the render check: content larger than its frame, cut off, wrapped onto a second line, or drawn at zero size. */
 export type RenderCheck = 'OVERFLOW' | 'CLIPPED' | 'WRAP' | 'ZERO-SIZE';
 
+/**
+ * The contrast check measures every text of every state against its drawn background, to WCAG 2 AA: 4.5:1, or
+ * 3:1 for large text; disabled text is exempt. `pairs` names token pairs it also computes, each `text` token on
+ * each `on` token of an entry, for example `{ text: ['--text', '--text-muted'], on: ['--surface'] }`.
+ * `exceptions` exempts the text inside each `selector`, with the `reason` it may stay below the limit.
+ */
+export type PartContrast = {
+  pairs?: { text: string[]; on: string[] }[];
+  exceptions?: { selector: string; reason: string }[];
+};
+
 /** How a composing part draws another one: `interaction` forces it on the root, as a frame does. */
 export type RenderOptions = { interaction?: Interaction };
 
 type PartSource<TProps, TState extends string, TColumn extends string> = Omit<
   Part<TProps, TState>,
-  'states' | 'grid' | 'render'
+  'states' | 'grid' | 'controls' | 'motions' | 'rules' | 'render'
 > & {
+  motions?: Record<string, Motion<NoInfer<TState>>>;
+  rules?: PartRule<NoInfer<TState>>[];
   states: Record<TState, NoInfer<TProps>>;
+  controls?: Record<string, Control<NoInfer<TState>>>;
   grid?: { columns: readonly TColumn[]; rows: Record<string, Partial<Record<NoInfer<TColumn>, NoInfer<TState>>>> };
   render: (props: TProps) => Drawing | Promise<Drawing>;
 };

package/design/morph.ts

@@ -0,0 +1,67 @@
+const keyOf = (node: Node) =>
+  node instanceof Element
+    ? `${node.nodeName}#${node.id}#${node.getAttribute('data-et-key') ?? ''}`
+    : `${node.nodeType}`;
+
+const morphAttributes = (from: Element, to: Element) => {
+  for (const { name } of [...from.attributes]) if (!to.hasAttribute(name)) from.removeAttribute(name);
+
+  for (const { name, value } of [...to.attributes])
+    if (from.getAttribute(name) !== value) from.setAttribute(name, value);
+};
+
+const morphNode = (from: Node, to: Node) => {
+  if (from instanceof Element && to instanceof Element) {
+    morphAttributes(from, to);
+    morphChildren(
+      from instanceof HTMLTemplateElement ? from.content : from,
+      to instanceof HTMLTemplateElement ? to.content : to,
+    );
+  } else if (from.nodeValue !== to.nodeValue) {
+    from.nodeValue = to.nodeValue;
+  }
+};
+
+const morphChildren = (from: Node, to: Node) => {
+  let cursor = from.firstChild;
+
+  for (const next of [...to.childNodes]) {
+    const key = keyOf(next);
+    let match: ChildNode | null = cursor;
+
+    while (match && keyOf(match) !== key) match = match.nextSibling;
+
+    if (match) {
+      while (cursor && cursor !== match) {
+        const removed: ChildNode = cursor;
+
+        cursor = cursor.nextSibling;
+        removed.remove();
+      }
+
+      morphNode(match, next);
+      cursor = match.nextSibling;
+    } else {
+      from.insertBefore(next, cursor);
+    }
+  }
+
+  while (cursor) {
+    const removed: ChildNode = cursor;
+
+    cursor = cursor.nextSibling;
+    removed.remove();
+  }
+};
+
+/**
+ * Turns the children of `root` into `markup` by changing only what differs: attributes, text, and the nodes that
+ * appear or go. A node is kept when its tag, `id` and `data-et-key` match one at the same place, so its CSS
+ * transitions run and a node that appears gets `@starting-style`.
+ */
+export const morph = (root: Element, markup: string) => {
+  const parsed = root.ownerDocument.createElement('template');
+
+  parsed.innerHTML = markup;
+  morphChildren(root, parsed.content);
+};

package/design/motion-runtime.ts

@@ -0,0 +1,200 @@
+import { Motion, MotionContext, PartRule } from './define-part';
+import { morph } from './morph';
+
+/** The time of a motion in ms from its start: `at` runs `fn` once `now` reaches `ms`, `advance` moves time on. */
+export type MotionClock = {
+  now: () => number;
+  at: (ms: number, fn: () => void) => void;
+  advance: (ms: number) => void;
+};
+
+/** A clock that only moves when `advance` is called, so a caller can pause and step a motion. */
+export const manualClock = (): MotionClock => {
+  let time = 0;
+  let queue: { ms: number; fn: () => void }[] = [];
+
+  return {
+    now: () => time,
+    at: (ms, fn) => {
+      queue.push({ ms, fn });
+    },
+    advance: (ms) => {
+      const target = time + ms;
+
+      for (;;) {
+        const due = queue.reduce<{ ms: number; fn: () => void } | null>(
+          (first, task) => (task.ms <= target && (!first || task.ms < first.ms) ? task : first),
+          null,
+        );
+
+        if (!due) break;
+
+        queue = queue.filter((task) => task !== due);
+        time = Math.max(time, due.ms);
+        due.fn();
+      }
+
+      time = target;
+    },
+  };
+};
+
+/** A clock that follows real time while it has work, one step per animation frame. */
+export const realTimeClock = (
+  frame: (step: () => void) => void = (step) => requestAnimationFrame(step),
+  wall: () => number = () => performance.now(),
+): MotionClock => {
+  const clock = manualClock();
+  let waiting = 0;
+  let last: number | null = null;
+
+  const tick = () => {
+    const now = wall();
+
+    clock.advance(now - (last ?? now));
+    last = now;
+
+    if (waiting > 0) frame(tick);
+    else last = null;
+  };
+
+  return {
+    ...clock,
+    at: (ms, fn) => {
+      waiting++;
+      clock.at(ms, () => {
+        waiting--;
+        fn();
+      });
+
+      if (last === null) {
+        last = wall();
+        frame(tick);
+      }
+    },
+  };
+};
+
+/** The same sequence in every run: mulberry32 from a fixed seed. */
+export const seededRandom = (seed = 1) => {
+  let state = seed >>> 0;
+
+  return () => {
+    state = (state + 0x6d2b79f5) >>> 0;
+
+    let value = Math.imul(state ^ (state >>> 15), 1 | state);
+
+    value ^= value + Math.imul(value ^ (value >>> 7), 61 | value);
+
+    return ((value ^ (value >>> 14)) >>> 0) / 4294967296;
+  };
+};
+
+const measure = (root: Element) => {
+  const rects = [...root.querySelectorAll('*')].map((element) => element.getBoundingClientRect());
+  const copy = root.cloneNode(true) as Element;
+  const copies = [...copy.querySelectorAll('*')];
+
+  return (selector: string) => {
+    const found = copy.querySelector(selector);
+    const rect = found ? rects[copies.indexOf(found)] : undefined;
+
+    if (!rect) throw new Error(`design-explore: ctx.rect("${selector}") matches nothing in the from state`);
+
+    return rect;
+  };
+};
+
+/** What a switch of `root` to `markup` does: `motion` names its `play` and `viewTransition`, `clock` the time `ctx.at` runs on. */
+export type StateSwitch = { root: Element; markup: string; motion?: Motion; clock?: MotionClock };
+
+/**
+ * Morphs `root` to `markup`, inside a View Transition when the motion asks for one and the browser has it, then runs
+ * the motion's `play`. `ctx.rect` measures in the DOM before the morph. Resolves once `play` has run.
+ */
+export const switchState = ({ root, markup, motion, clock }: StateSwitch): Promise<void> => {
+  const rect = motion?.play ? measure(root) : null;
+  const apply = () => morph(root, markup);
+  const play = () => {
+    if (!motion?.play || !rect) return;
+
+    const time = clock ?? realTimeClock();
+    const ctx: MotionContext = { at: (ms, fn) => time.at(ms, fn), random: seededRandom(), rect };
+
+    motion.play(ctx);
+  };
+  const document = root.ownerDocument;
+
+  if (motion?.viewTransition && typeof document.startViewTransition === 'function')
+    return document.startViewTransition(apply).updateCallbackDone.then(play);
+
+  apply();
+  play();
+
+  return Promise.resolve();
+};
+
+/**
+ * How `runRules` reaches the part: the state drawn first, its `rules` and `motions`, and the markup of a state. `clock`
+ * makes the clock of each switch, `switched` hears each finished switch and `failed` each error.
+ */
+export type PartRules = {
+  state: string;
+  rules: PartRule[];
+  motions?: Record<string, Motion>;
+  render: (state: string) => string | Promise<string>;
+  clock?: () => MotionClock;
+  switched?: (state: string) => void;
+  failed?: (error: unknown) => void;
+};
+
+/**
+ * Runs the rules of a part in `root`: an event that matches a rule's `on`, such as `click .open`, morphs the part to the
+ * rule's state with the motion it names. Switches run one after another. Returns a function that stops the rules.
+ */
+export const runRules = (root: HTMLElement, part: PartRules) => {
+  let current = part.state;
+  let queue = Promise.resolve();
+  const types = [...new Set(part.rules.map((rule) => rule.on.trim().split(/\s+/u)[0] ?? ''))].filter(Boolean);
+
+  const go = (rule: PartRule) => {
+    queue = queue
+      .then(() => (rule.to === current ? null : part.render(rule.to)))
+      .then((markup) => {
+        if (markup === null) return;
+
+        current = rule.to;
+
+        return switchState({
+          root,
+          markup,
+          motion: rule.motion ? part.motions?.[rule.motion] : undefined,
+          clock: part.clock?.(),
+        }).then(() => part.switched?.(rule.to));
+      })
+      .catch((error: unknown) => (part.failed ?? console.error)(error));
+  };
+
+  const listener = (event: Event) => {
+    const target = event.target instanceof Element ? event.target : null;
+    const rule = part.rules.find((entry) => {
+      const [type = '', ...rest] = entry.on.trim().split(/\s+/u);
+      const selector = rest.join(' ');
+
+      if (type !== event.type) return false;
+      if (!selector) return true;
+
+      const matched = target?.closest(selector);
+
+      return matched ? root.contains(matched) : false;
+    });
+
+    if (rule) go(rule);
+  };
+
+  for (const type of types) root.addEventListener(type, listener);
+
+  return () => {
+    for (const type of types) root.removeEventListener(type, listener);
+  };
+};

package/design/web/env.d.ts

@@ -9,8 +9,12 @@ declare module 'virtual:design-explore/env' {
   export const loadEnv: (project: string) => Promise<unknown>;
   /** The theme names the config declares for the project. The first of each list is the default. */
   export const themesOf: (project: string) => { surface: string[]; color: string[] };
-  /** Loads the stylesheet a product draws under, which its base parts draw under too. */
-  export const loadProductEnv: (product: string) => Promise<unknown>;
+  /** Loads the stylesheet a product, or one variant of one of its sketches, draws under, which its base parts draw under too. */
+  export const loadProductEnv: (options: {
+    product: string;
+    sketch: string | null;
+    variant: string;
+  }) => Promise<unknown>;
 }
 
 declare module 'virtual:design-explore/system' {

package/design/web/frame.ts

@@ -1,5 +1,7 @@
 import { CallVariant, Drawing, mountDrawing, placeOverlays } from '../define-call';
+import { Part } from '../define-part';
 import { fitEmbed } from '../embed-page';
+import { runRules } from '../motion-runtime';
 import { calls } from 'virtual:design-explore';
 import { loadEnv, loadProductEnv } from 'virtual:design-explore/env';
 import { parts, sketchParts, sketchTokens, tokens } from 'virtual:design-explore/system';
@@ -77,6 +79,8 @@ const showSetupError = (message: string) => {
 
 const messageOf = (error: unknown) => (error instanceof Error ? error.message : String(error));
 
+let drawnPart: { part: Part<unknown>; states: Record<string, unknown> } | null = null;
+
 const drawCall = async (): Promise<Drawing | null> => {
   const call = calls[slug];
   if (!call) return fail(`design-explore: no call "${slug}"`);
@@ -110,6 +114,8 @@ const drawPart = async (name: string): Promise<Drawing | null> => {
 
     if (!(key in holder.states)) return fail(`design-explore: part "${partKey}" has no state "${key}"`);
 
+    drawnPart = { part: part as Part<unknown>, states: holder.states };
+
     return await part.render(holder.states[key]);
   } catch (error) {
     return fail(`design-explore: state "${key}" of "${partKey}" failed\n${messageOf(error)}`);
@@ -162,10 +168,40 @@ const report = () => {
   );
 };
 
+const runPartRules = ({ part, states }: NonNullable<typeof drawnPart>, styles: string) => {
+  const sheets = new Set([styles]);
+
+  runRules(root, {
+    state: key,
+    rules: part.rules ?? [],
+    motions: part.motions,
+    render: (state) =>
+      Promise.resolve(part.render(states[state])).then((drawn) =>
+        sheets.has(drawn.styles)
+          ? drawn.body
+          : forced(drawn.styles).then((css) => {
+              const style = document.createElement('style');
+
+              sheets.add(drawn.styles);
+              style.textContent = css;
+              document.head.append(style);
+
+              return drawn.body;
+            }),
+      ),
+    switched: () => {
+      const partRoot = partRootOf(root);
+
+      if (interaction && partRoot) force(partRoot, interaction);
+    },
+    failed: (error) => showSetupError(`design-explore: switch of part "${partKey}" failed\n${messageOf(error)}`),
+  });
+};
+
 // macOS WebKit can loop in module evaluation when a frame with top-level await is removed.
 const drawFrame = async () => {
   parent.postMessage({ type: 'design-explore:loading' }, '*');
-  await (product ? loadProductEnv(product) : loadEnv(slug.split('/')[0] ?? ''));
+  await (product ? loadProductEnv({ product, sketch, variant: sketchVariant }) : loadEnv(slug.split('/')[0] ?? ''));
   const tokenStyles = product ? await tokensOf(product) : null;
   const loaded = await (product ? drawPart(product) : drawCall());
 
@@ -188,6 +224,8 @@ const drawFrame = async () => {
 
     if (error)
       showSetupError(`design-explore: setup of ${product ? 'state' : 'variant'} "${key}" failed\n${messageOf(error)}`);
+
+    if (drawnPart?.part.rules?.length) runPartRules(drawnPart, loaded.styles ?? '');
   }
 
   const place = () => placeOverlays(root);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ethlete/cli",
-  "version": "3.0.0-next.23",
+  "version": "3.0.0-next.24",
   "repository": {
     "type": "git",
     "url": "https://github.com/ethlete-io/ethdk",
@@ -14,6 +14,7 @@
     "et": "./src/index.js"
   },
   "dependencies": {
+    "@tailwindcss/node": "4.3.3",
     "@tailwindcss/postcss": "4.3.3",
     "postcss": "8.5.32",
     "postcss-selector-parser": "7.1.7",

package/src/lib/design/changed-parts.d.ts

@@ -34,10 +34,10 @@ export declare const changedPartsOf: (options: {
     dependents: string[];
 }) => PartsChange;
 /**
- * The frames a file that came or went redraws: every part of the product whose part folder holds it,
- * since an `@system/...` import anywhere in the product may now resolve to another file, or the parts
- * of the variant whose folder holds it. A file in no part folder redraws no part, only the frames
- * that show an error.
+ * The frames a file that came or went redraws: every part of the product whose part folder or `shared/`
+ * holds it, since an `@system/...` or `@shared/...` import anywhere in the product may now resolve to
+ * another file, or the parts of the variant whose folder holds it. A file in no part folder redraws no
+ * part, only the frames that show an error.
  */
 export declare const addedPartsOf: (options: {
     designRoot: string;