@ethlete/cli 3.0.0-next.25 → 3.0.0-next.26

package/CHANGELOG.md

@@ -1,5 +1,94 @@
 # @ethlete/cli
 
+## 3.0.0-next.26
+
+### Minor Changes
+
+- `et design check` measures text contrast in each colour scheme a product renders (light and dark when its stylesheets use `prefers-color-scheme` or `light-dark()`) and names the scheme in a CONTRAST finding.
+- `et design` takes a product `base` from `node_modules`: `render.packages` defaults to `node_modules` without `dist/libs`, and an installed base gets no generated `tsconfig.json`.
+- The `et design mcp` `check` tool checks a call and its variant, and `et design check --receipt <path>` writes the result to a JSON file.
+- The new `call` tool of `et design mcp` reads a call: its `call.ts`, its `fixture.ts`, the variant file and the frame URL.
+- A design part can name its component with `implements`, and `et design check` prints the open points of each part.
+- A design product can declare the colour schemes it draws with `schemes` in `.ethlete/design/config.json`; both when left out.
+- The design server answers `GET /__design/queue` with its queued and drawing shots, the age of the oldest, and the last shots that failed.
+- A design product can list `generatedFiles` in its config. The part hash skips them, so regenerating a file no longer makes `design check` warn that the part changed outside a sketch.
+- Add `iconSheet` to `@design-system`: a shared icon foundation sheet with a `catalogue` and a `construction` view, drawing each icon on its own grid (from its viewBox or `grid`) with centre lines and the padding box.
+- `design complete` counts an option or a `row` control with `data-active-source="keyboard"` as its focus-visible look, the same as an option named by `aria-activedescendant`.
+- `@design-system` exports `logoSheet({ marks })`, which draws a `foundations/logo` part: each mark at its sizes, with an optional light bar.
+- `et design shot` and `et design motion` take `--scheme <light|dark>` (MCP: `scheme`) to draw a part in that colour scheme.
+- Add `et design sketch note <layer>/<name> <variant> <text> --by <model id>`: it sets the note of one variant in sketch.json and refuses an unknown sketch or variant.
+- `et design check`, `sketch check`, `sketch ready` and `design complete` fail interaction states on a part that declares no control (`CONTROL-STATE`). `design complete` hints a state that changes under 10 % of its frame.
+- `et design check` lists missing motions as open points: every ordered state pair, except focus, and a looping motion in an ongoing-work state. `definePart({ unreachable })` exempts a pair with a reason, checked by the `MOTION-UNREACHABLE-*` rules.
+- The design render check measures non-text contrast: the border of each control (and the frame around an input) and each svg icon must reach 3:1 against what it sits on. Decorative borders give no finding.
+- `et design check` lists two more open points: a component part with no controls declared, and the contrasts the render check found. With `--complete`, it also lists each control that lacks a drawn state or surface.
+- The design server answers `GET /__design/open-points?product=&part=`, the open-point list of one part or of every part; `draw=true` adds the contrasts and missing control states of one part.
+- Design checks report missing mock option values as hints for merged parts and block newly introduced gaps in sketches; use `omits` to record intentional omissions.
+- `et design ready <part>` and `POST /__design/part-ready` mark a part ready in `ready.json`, refused while the part has open points; the mark drops when the part changes.
+- `et design` shot requests take `view` (a number raised per view change) and `rank=active|visible`: the active frame of the shown view draws first, then its visible cells, then the rest, then older views. A hung-up request's queued shot is dropped.
+- `et design sketch ready` refuses while a target in a live variant has open points the sketch can close: no controls declared or a missing motion.
+- The Studio motion timeline makes the motion's start frame live and drives it: the slider pauses its animations at that time, play and speed run them, closing resumes them at 1x.
+- Motion timeline tracks name the foundations duration and easing tokens they use.
+- `et design sketch ready` now runs the render check on the sketch's variants and refuses on any render issue, as `sketch check` reports it. Skipped elements are honoured; without a browser the check is skipped.
+
+### Patch Changes
+
+- `et design check` now lists the findings of a base product's parts per rule and says they do not block the product, instead of pointing to `--product <base>`.
+- A design product without its own `tokens` takes the token parts of its base, so frames of a product that extends a base draw under the base's tokens.
+- `et design complete` no longer crashes on an option that is also a `data-et-control` in an open surface.
+- The design contrast check measures text against a `z-index: -1` fill behind it (a positioned sibling or a `::before`/`::after`) instead of the panel under that fill.
+- `et design complete` no longer fails a page on the gaps of a control part it uses from its base product; those gaps stay open points of the base part.
+- `et design check` no longer fails a product on the findings of a part it takes from its base product. It counts them in one line that points to the base product's own check.
+- `et design check` prints one `RENDER CHECK NOT RUN` line when failing checks stop the render, naming the rules and how many problems are in the base.
+- `et design` commands that load design modules (`system --json`, `sketch ready`) no longer share the dependency cache of the running design server, so they stop deleting its optimized deps and blanking every live frame.
+- `et design complete` reports `CONTROL-UNDECLARED` as a hint; the sketch check fails on a control a sketch adds. For a native control the hint says to mark it with `control(markup, name)` and declare the name in `controls`.
+- `et design` listens on `DE_PORT` when it is set, also when Studio did not start it. Before, it took a free port.
+- `design complete` no longer reports the focus container of a composite widget (a `menu`, `listbox`, `tree`, `grid`, `tablist` or similar with `tabindex="-1"` or `aria-activedescendant`) as an undeclared control; its items are still checked.
+- A package rebuild that writes a file back unchanged no longer redraws the design shots that use it.
+- `et design complete` requires hover, focus and active of a menu item but no selected look; a select still requires the selected look.
+- The design server keeps its part shots on disk, so a restart serves them without redrawing until a file they draw from changes.
+- `et design complete` names a `hover:`, `active:` or `focus:` class no stylesheet defines instead of reporting an unchanged box, and the Studio Tailwind theme gains the `surface-pressed` colour.
+- A design frame no longer grows below a scroll container for an absolute element that the container clips, such as the scroll sentinels of an overlay body.
+- A design frame no longer grows to the viewport for a fixed element on all four edges, such as an overlay backdrop.
+- A part frame now grows to cover absolutely or fixed positioned content, so an open overlay panel no longer gets cut off at the trigger's height.
+- Design tool: a forced `focus-visible` now also matches `:focus-within` on the element and its ancestors, so floating labels and focus rings draw as they do in a real focus.
+- A shot of a missing part, state or sketch variant now always answers 404, a queued shot of a removed sketch is dropped, and the render queue no longer lists failures of removed sketches.
+- A part shot is cut from the page with a clip of the root's box instead of an element screenshot, and the thumb queue draws eight shots at once instead of four, so a grid of forty states draws faster.
+- `et design shot --crop changed` also crops the states the merged part does not draw, comparing them with its first state, so a new hover state is no longer cut off.
+- `et design sketch check` and `sketch ready` print one count line per variant for the problems that were there before, instead of repeating each of them per variant.
+- The design server lists sketches about three times faster: each part source is parsed once, and the product's rule problems are found once per list. A run of merges no longer stalls frames and Studio requests for seconds.
+- The sketch check warns of an export in a sketch's `shared/` folder only when no variant imports it. An export that only some variants use no longer warns.
+- The `STALE-REPLACE` design check no longer warns on a `.replace` on a function parameter that a call fills with markup from a package.
+- `et design check` no longer reports an `rgb()` or `rgba()` as a hard-coded colour when every channel comes from `var()`, for example `rgb(var(--shadow-rgb) / 0.25)`. A literal channel is still reported.
+- Draw part and call shots on a transparent page in both colour schemes, as a live frame does.
+- `et design check` reports `CONTROL-PART-INPUT` again: an import cycle left the plain-control selector undefined, so the rule matched no element.
+- The CONTROL-PART-INPUT hint now covers the same plain controls as `design complete`: `summary`, focusable `[tabindex]` and every interactive role.
+- CONTROL-STATE counts an interaction word only as the last word of a state name, drops modifier words from the element name, and asks a component without controls to declare them (Q164).
+- Design commands that run at the same time no longer share one Vite cache folder: the first keeps the shared cache, every other one draws from a folder of its own that it removes when it closes.
+- The design contrast check no longer reports decorative separators, toolbar outlines or hidden svg lines, and measures text on a frame's page fill.
+- The contrast check measures the border of a segmented group: a bordered wrapper counts as a control frame when all its controls together fill at least half of it. Toolbars stay excluded.
+- Design checks report a drawn button, link, input or control role without `data-et-control` as `CONTROL-PART-INPUT`: a hint on merged parts, an error when a sketch adds one.
+- Design checks now list existing interaction states on non-control parts as open points while blocking new or changed states in sketches.
+- Design sketch checks accept unchanged interaction states when unrelated styles change.
+- The design server no longer crashes when a sketch folder disappears while sketches are listed.
+- The design server's parts list names each part's module file, relative to the workspace.
+- The design server no longer pre-bundles its own authoring modules (`@design-system`, `@design-system/kit`, `@design-explore`), so a cold start no longer reloads every frame when Vite finds one of them late.
+- The design server draws a rebuilt `render.packages` folder (such as `dist/libs/components`) without a restart, instead of serving the modules it loaded before the rebuild.
+- Serve a shot from the disk cache after the design server restarts, instead of drawing it again
+- Every design shot response carries an `x-design-shot` header (`disk`, `memory` or `drawn`) that says where the picture came from.
+- `sketch check` no longer prints Angular's development mode line per render, and prints a finding that repeats across states, schemes and variants once, with a count.
+- `et design sketch merge` formats the files it writes with the Prettier of the target repo. A format failure prints a warning and keeps the merge.
+- `et design sketch ready` blocks only on open points a variant adds to the merged part; inherited points are listed as a note. A new part still blocks on all of its points.
+- `et design sketch variant --from` keeps relative symlinks in the copied variant, so its `shared/` links point at the same files as the source variant.
+- `et design` no longer rewrites an unchanged tsconfig, so a `design sketch check` stops redrawing every frame in Studio.
+- A rule in a sketch's `shared/` stylesheet counts as used when any variant of the sketch draws it, so `sketch ready` no longer fails a variant on `UNUSED` for a rule only another variant uses.
+- A design frame asked for a `fill` token its product lacks keeps the product's page colour, so an sdk grid cell in the light column draws on the light surface instead of on Studio's dark canvas.
+- `et design shot <part> --variants` finds a sketch by an extra target, `sketch list` shows extra targets, and new `sketch target add <sketch> <part>` adds a target to an open sketch.
+- `et design sketch report` on a ready sketch moves it back to in progress. It still refuses a decided sketch.
+- STALE-REPLACE no longer flags a replace whose regex is anchored with `^` or `$`; the rule searches the source, not the markup string.
+- A static shot draws in the colour scheme Studio prefers, like the live frames next to it, so a dark Studio no longer mixes light shots into a grid.
+- Studio draws every part grid twice, under a Light and a Dark head, and `frame.html?scheme=` pins a live frame to one scheme.
+- Swap a canvas frame between its shot and its live page without a blank frame: the frame page reports when it painted, and Studio keeps the old view until the new one is ready.
+
 ## 3.0.0-next.25
 
 ### Minor Changes

package/design/define-call.ts

@@ -248,7 +248,8 @@ export const placeOverlays = (root: HTMLElement) => {
 /**
  * Grows `root` to cover every absolutely or fixed positioned element inside it, such as an open
  * overlay pane, so a frame measured or shot from `root` shows them. Skips a fixed element on all four
- * edges of the viewport, such as a backdrop. Grows sideways too with `sideways`. Safe to run again.
+ * edges of the viewport, such as a backdrop, and counts an absolute element only as far as the
+ * overflow boxes that clip it. Grows sideways too with `sideways`. Safe to run again.
  */
 export const fitOutOfFlow = (root: HTMLElement, options: { sideways: boolean }) => {
   const view = root.ownerDocument.defaultView;
@@ -260,11 +261,36 @@ export const fitOutOfFlow = (root: HTMLElement, options: { sideways: boolean })
   const fillsViewport = (style: CSSStyleDeclaration) =>
     style.position === 'fixed' &&
     [style.top, style.right, style.bottom, style.left].every((edge) => parseFloat(edge) === 0);
+  const clips = (style: CSSStyleDeclaration) =>
+    [style.overflow, style.overflowX, style.overflowY].some((overflow) => overflow && overflow !== 'visible');
+  const holdsAbsolute = (style: CSSStyleDeclaration) =>
+    !['static', ''].includes(style.position) || !['none', ''].includes(style.transform);
+  const clipped = (element: Element) => {
+    let { top, right, bottom, left } = element.getBoundingClientRect();
+    let escaping = true;
+
+    for (let ancestor = element.parentElement; ancestor && ancestor !== root; ancestor = ancestor.parentElement) {
+      const style = view.getComputedStyle(ancestor);
+
+      if (escaping && holdsAbsolute(style)) escaping = false;
+      if (!escaping && clips(style)) {
+        const box = ancestor.getBoundingClientRect();
+
+        top = Math.max(top, box.top);
+        right = Math.min(right, box.right);
+        bottom = Math.min(bottom, box.bottom);
+        left = Math.max(left, box.left);
+      }
+      if (style.position === 'fixed') break;
+      if (style.position === 'absolute') escaping = true;
+    }
+
+    return { top, right, bottom, left, width: right - left, height: bottom - top };
+  };
   const outOfFlow = [...root.querySelectorAll('*')]
     .map((element) => ({ element, style: view.getComputedStyle(element) }))
     .filter(({ style }) => ['absolute', 'fixed'].includes(style.position) && !fillsViewport(style))
-    .map(({ element }) => element)
-    .map((element) => element.getBoundingClientRect())
+    .map(({ element, style }) => (style.position === 'fixed' ? element.getBoundingClientRect() : clipped(element)))
     .filter((rect) => rect.width > 0 && rect.height > 0);
   const extentOf = ({ side, start, paddings }: { side: 'bottom' | 'right'; start: number; paddings: string[] }) => {
     const extent = Math.max(0, ...outOfFlow.map((rect) => Math.ceil(rect[side] - start)));

package/design/define-part.ts

@@ -10,6 +10,8 @@ export { iconSheet } from './icon-sheet';
 export type { IconSheetIcon, IconSheetOptions } from './icon-sheet';
 export { interactionRows } from './interaction-rows';
 export type { InteractionRowsOptions } from './interaction-rows';
+export { logoSheet } from './logo-sheet';
+export type { LogoSheetMark, LogoSheetOptions } from './logo-sheet';
 export { spring } from './spring';
 export type { Spring } from './spring';
 export { svgAsset } from './svg-asset';
@@ -33,10 +35,13 @@ export type Interaction = 'hover' | 'focus-visible' | 'active' | 'disabled';
  * `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.
+ * `unreachable` lists the state pairs no user can move between, each with its `reason`; they need no motion.
+ * `omits` records mock option values deliberately left off the grid, each with a reason.
  * `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`.
+ * `implements` links the part to the code that builds it, see `PartLink`.
  */
 export type Part<TProps, TState extends string = string> = {
   note: string;
@@ -50,10 +55,19 @@ export type Part<TProps, TState extends string = string> = {
   checks?: { skip?: RenderCheck[] };
   contrast?: PartContrast;
   motions?: Record<string, Motion<TState>>;
+  unreachable?: { from: TState; to: TState; reason: string }[];
+  omits?: { option: keyof TProps & string; value: string; reason: string }[];
   rules?: PartRule<TState>[];
+  implements?: PartLink;
   render: (props: TProps, options?: RenderOptions) => DrawnPart | Promise<DrawnPart>;
 };
 
+/**
+ * The code a part is built in: a component or element names the repo-relative path of its `.component.ts`, a page
+ * names its route. `design check` fails on a path that does not exist, and lists a part without a link as open.
+ */
+export type PartLink = `${string}.component.ts` | { route: `/${string}` };
+
 /** 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;
@@ -62,7 +76,7 @@ export type MotionContext = {
 };
 
 /**
- * A motion from the state `from` to the state `to`. `at` adds shot times in ms, `interrupt` starts the reverse motion
+ * A motion from the state `from` to the state `to`; with `from` equal to `to` it is the looping motion inside that state. `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> = {

package/design/logo-sheet.ts

@@ -0,0 +1,52 @@
+import { Drawing, html } from './define-call';
+import { svgAsset } from './svg-asset';
+
+export type LogoSheetMark = {
+  title: string;
+  svg: string;
+  sizes: number[];
+  onLight?: number[];
+};
+
+export type LogoSheetOptions = {
+  marks: LogoSheetMark[];
+};
+
+const SHEET_STYLES = `
+  .lgs-root { display: flex; flex-direction: column; gap: var(--space-4, 1.6rem); padding: var(--space-6, 2.4rem); background: var(--surface, oklch(0.17 0 0)); color: var(--text, oklch(0.94 0 0)); font-family: var(--font-ui, system-ui, -apple-system, "Segoe UI", Roboto, sans-serif); font-size: var(--text-md, 1.3rem); line-height: var(--text-md-line, 1.8rem); }
+  .lgs-root svg { display: block; }
+  .lgs-title { margin: 0; font-size: var(--text-xl, 1.7rem); line-height: var(--text-xl-line, 2.2rem); font-weight: var(--weight-strong, 600); }
+  .lgs-row { display: flex; align-items: flex-end; gap: var(--space-6, 2.4rem); }
+  .lgs-item { display: flex; flex-direction: column; align-items: center; gap: var(--space-2, 0.8rem); }
+  .lgs-label { font-family: var(--font-code, ui-monospace, "SF Mono", Menlo, Consolas, monospace); font-size: var(--text-xs, 1rem); line-height: var(--text-xs-line, 1.4rem); color: var(--text-muted, oklch(0.72 0 0)); }
+  .lgs-plate { display: flex; align-items: center; gap: var(--space-3, 1.2rem); padding: var(--space-2, 0.8rem) var(--space-3, 1.2rem); border-radius: var(--radius-control-md, 0.6rem); background: var(--text, oklch(0.94 0 0)); }
+`;
+
+const item = (content: string, label: string) =>
+  html`<div class="lgs-item">${content}<span class="lgs-label">${label}</span></div>`;
+
+/**
+ * Draws a `foundations/logo` part: one row per mark with its `title`, the mark at each of its `sizes` in px, and, when
+ * `onLight` lists sizes, the mark at those sizes on a light bar.
+ */
+export const logoSheet = ({ marks }: LogoSheetOptions): Drawing => ({
+  body: html`<div class="lgs-root">
+    ${marks
+      .map(
+        ({ title, svg, sizes, onLight }) =>
+          html`<h2 class="lgs-title">${title}</h2>
+            <div class="lgs-row">
+              ${sizes.map((size) => item(svgAsset(svg, { size }), `${size} px`)).join('')}
+              ${
+                !!onLight?.length &&
+                item(
+                  html`<div class="lgs-plate">${onLight.map((size) => svgAsset(svg, { size })).join('')}</div>`,
+                  'on a light bar',
+                )
+              }
+            </div>`,
+      )
+      .join('')}
+  </div>`,
+  styles: SHEET_STYLES,
+});

package/design/motion-drive.ts

@@ -0,0 +1,215 @@
+import { SteppedMotion } from './motion-runtime';
+
+/** What the Studio timeline posts into a live frame to drive a motion of its part. */
+export type MotionDriveMessage =
+  | { type: 'design-explore:motion-start'; motion: string; reduced: boolean }
+  | { type: 'design-explore:motion-seek'; ms: number; rate: number }
+  | { type: 'design-explore:motion-play'; ms: number; rate: number }
+  | { type: 'design-explore:motion-stop' };
+
+/** What a live frame posts back once a motion started, or failed to. */
+export type MotionDriveReply =
+  | { type: 'design-explore:motion-ready'; motion: string }
+  | { type: 'design-explore:motion-failed'; motion: string; error: string };
+
+const TAIL_MS = 30000;
+
+const isTime = (value: unknown): value is number => typeof value === 'number' && Number.isFinite(value) && value >= 0;
+
+const isRate = (value: unknown): value is number => typeof value === 'number' && Number.isFinite(value) && value > 0;
+
+/** The drive message `data` holds, or `null` for any other message. */
+export const motionDriveMessageOf = (data: unknown): MotionDriveMessage | null => {
+  if (typeof data !== 'object' || data === null) return null;
+
+  const message = data as Record<string, unknown>;
+
+  switch (message['type']) {
+    case 'design-explore:motion-start':
+      return typeof message['motion'] === 'string'
+        ? { type: message['type'], motion: message['motion'], reduced: message['reduced'] === true }
+        : null;
+    case 'design-explore:motion-seek':
+    case 'design-explore:motion-play':
+      return isTime(message['ms']) && isRate(message['rate'])
+        ? { type: message['type'], ms: message['ms'], rate: message['rate'] }
+        : null;
+    case 'design-explore:motion-stop':
+      return { type: message['type'] };
+    default:
+      return null;
+  }
+};
+
+const REDUCED_FEATURE = /\(\s*prefers-reduced-motion\s*(?::\s*(reduce|no-preference)\s*)?\)/g;
+const ALWAYS = '(min-width: 0px)';
+const NEVER = '(max-width: -1px)';
+
+type MediaHolder = CSSRule & { media: MediaList };
+
+const mediaRulesOf = (rules: CSSRuleList): MediaHolder[] =>
+  [...rules].flatMap((rule) =>
+    'cssRules' in rule
+      ? [...('media' in rule ? [rule as MediaHolder] : []), ...mediaRulesOf((rule as CSSGroupingRule).cssRules)]
+      : [],
+  );
+
+const sheetRulesOf = (sheet: CSSStyleSheet) => {
+  try {
+    return mediaRulesOf(sheet.cssRules);
+  } catch {
+    return [];
+  }
+};
+
+/**
+ * Makes every `prefers-reduced-motion` media rule of `document` match as if the user asked for `reduced` motion, and
+ * returns a function that puts the rules back. Scripts that call `matchMedia` still see the real preference.
+ */
+export const emulateReducedMotion = (document: Document, reduced: boolean) => {
+  const changed = [...document.styleSheets].flatMap(sheetRulesOf).flatMap((rule) => {
+    const original = rule.media.mediaText;
+    const emulated = original.replace(REDUCED_FEATURE, (_, value?: string) =>
+      (value === 'no-preference' ? !reduced : reduced) ? ALWAYS : NEVER,
+    );
+
+    if (emulated === original) return [];
+
+    rule.media.mediaText = emulated;
+
+    return [{ rule, original }];
+  });
+
+  return () => {
+    for (const { rule, original } of changed) rule.media.mediaText = original;
+  };
+};
+
+/**
+ * Drives a motion in a live frame from drive messages: `start` (re)starts the motion from its `from` state, a seek
+ * pauses every animation of the document at that time, play runs the motion's clock and animations at `rate`, and
+ * stop resumes every animation at 1x. `released` hears each stop.
+ */
+export const createMotionDriver = (options: {
+  document: Document;
+  start: (motion: string, reduced: boolean) => Promise<SteppedMotion>;
+  reply: (reply: MotionDriveReply) => void;
+  released?: () => void;
+  frame?: (step: (time: number) => void) => unknown;
+}) => {
+  const { document, reply } = options;
+  const frame = options.frame ?? ((step: (time: number) => void) => requestAnimationFrame(step));
+  let started: { motion: string; reduced: boolean } | null = null;
+  let stepped: SteppedMotion | null = null;
+  let loop = 0;
+  let queue: Promise<void> = Promise.resolve();
+
+  const holdAll = (rate: number) => {
+    for (const animation of document.getAnimations()) {
+      animation.pause();
+      animation.playbackRate = rate;
+    }
+  };
+
+  const resumeAll = () => {
+    for (const animation of document.getAnimations()) {
+      const end = animation.effect?.getComputedTiming().endTime;
+
+      animation.playbackRate = 1;
+
+      if (typeof end === 'number' && Number.isFinite(end) && Number(animation.currentTime ?? 0) >= end)
+        animation.finish();
+      else animation.play();
+    }
+  };
+
+  const run = (play: { motion: SteppedMotion; from: number; rate: number; step: () => void }) => {
+    const { motion, rate, step } = play;
+    const id = ++loop;
+    let time = play.from;
+    let last: number | null = null;
+
+    const tick = (now: number) => {
+      if (id !== loop) return;
+
+      time += (now - (last ?? now)) * rate;
+      last = now;
+      motion.seek(Math.min(time, TAIL_MS));
+      step();
+
+      if (time < TAIL_MS) frame(tick);
+    };
+
+    frame(tick);
+  };
+
+  const moveTo = (ms: number): Promise<SteppedMotion | null> => {
+    if (!stepped || !started) return Promise.resolve(null);
+    if (ms >= stepped.now()) {
+      stepped.seek(ms);
+
+      return Promise.resolve(stepped);
+    }
+
+    return options.start(started.motion, started.reduced).then((restarted) => {
+      stepped = restarted;
+      restarted.seek(ms);
+
+      return restarted;
+    });
+  };
+
+  const handled = (message: MotionDriveMessage): Promise<void> => {
+    loop++;
+
+    switch (message.type) {
+      case 'design-explore:motion-start':
+        started = { motion: message.motion, reduced: message.reduced };
+        stepped = null;
+
+        return options.start(message.motion, message.reduced).then(
+          (motion) => {
+            stepped = motion;
+            reply({ type: 'design-explore:motion-ready', motion: message.motion });
+          },
+          (error: unknown) =>
+            reply({
+              type: 'design-explore:motion-failed',
+              motion: message.motion,
+              error: error instanceof Error ? error.message : String(error),
+            }),
+        );
+      case 'design-explore:motion-seek':
+        return moveTo(message.ms).then((motion) => {
+          if (motion) holdAll(message.rate);
+        });
+      case 'design-explore:motion-play':
+        return moveTo(message.ms).then((motion) => {
+          if (!motion) return;
+
+          holdAll(message.rate);
+          run({ motion, from: message.ms, rate: message.rate, step: () => holdAll(message.rate) });
+        });
+      case 'design-explore:motion-stop': {
+        const motion = stepped;
+
+        if (!motion) return Promise.resolve();
+
+        motion.release();
+        resumeAll();
+        options.released?.();
+        run({ motion, from: motion.now(), rate: 1, step: () => undefined });
+
+        return Promise.resolve();
+      }
+    }
+  };
+
+  return {
+    handle: (message: MotionDriveMessage) => {
+      queue = queue.then(() => handled(message)).catch(() => undefined);
+
+      return queue;
+    },
+  };
+};

package/design/motion-runtime.ts

@@ -162,9 +162,14 @@ export type MotionTrack = {
   end: number | null;
 };
 
-/** A motion paused at its start: `seek` moves it forward to a time in ms, `tracks` lists what ran so far. */
+/**
+ * A motion paused at its start: `seek` moves it forward to a time in ms, `tracks` lists what ran so far. `release`
+ * stops pausing and posing its animations, so a later `seek` only runs its `ctx.at` steps.
+ */
 export type SteppedMotion = {
   seek: (ms: number) => void;
+  now: () => number;
+  release: () => void;
   tracks: () => MotionTrack[];
   end: () => number;
   bounds: () => MotionBox;
@@ -238,6 +243,7 @@ export const stepMotion = (options: {
   const cut = new Set<Animation>();
   const interrupt = motion.interrupt;
   let interrupted = false;
+  let released = false;
   let lastTask = 0;
   let ready: Promise<unknown> = Promise.resolve();
 
@@ -257,12 +263,14 @@ export const stepMotion = (options: {
     for (const animation of document.getAnimations()) {
       if (started.has(animation)) continue;
 
-      animation.pause();
+      if (!released) animation.pause();
       started.set(animation, trackOf(animation, start));
     }
   };
 
   const pose = (ms: number) => {
+    if (released) return;
+
     for (const [animation, track] of started)
       if (!cut.has(animation)) animation.currentTime = Math.max(0, ms - track.start);
   };
@@ -318,6 +326,10 @@ export const stepMotion = (options: {
 
           pose(ms);
         },
+        now: () => clock.now(),
+        release: () => {
+          released = true;
+        },
         tracks: () => [...started.values()],
         end: () => Math.max(lastTask, ...[...started.values()].map((track) => track.end ?? 0)),
         bounds: () => {