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

package/CHANGELOG.md

@@ -1,5 +1,90 @@
 # @ethlete/cli
 
+## 3.0.0-next.25
+
+### Minor Changes
+
+- `et design mcp` serves the design tools to an MCP client over stdio: parts, check, shot, motion_shots, the sketch commands and the inbox. `shot` and `motion_shots` return the sheet image; `motion_shots` also returns its JSON.
+- The design server answers `GET /__design/motion` with the keyframes and tracks of one motion mode, and each keyframe as a PNG with `frame=<ms>`. The draw is kept until the part changes.
+- `embedPage` takes `mark` and `css`, both applied inside the embedded page: every element matching `mark` gets an accent outline, and `css` is added as a stylesheet there.
+- `et design check` warns with `EMBED-SCALE` when an element around an `embedPage` frame with a `scale` scales it again, so the page shrinks twice.
+- `et design complete` accepts a `field` control kind for text fields: it needs a drawn hover and focus-visible, but no active.
+- The shot sheet draws an empty "not drawn" cell for each state combo a grid row leaves out, and `sketch check` lists those cells on the grid line.
+- `et design motion flow <flow> <line>` draws a flow line with `"transition": "view"` as a stepped View Transition from the `from` page to the `to` page, shot in the preset viewport. Lines are named by `id` or `from→to`.
+- `et design motion shots` clips each shot to the part and every animated element over all keyframes, so an overshoot is not cut off, and names a track's element by `data-et-key` where it has one.
+- Add `et design motion shots <part> <motion>`: it draws a motion at its keyframes in full and reduced motion into one sheet and writes its tracks as JSON.
+- `spring({ damping, frequency })` from `@design-system` returns a `linear()` easing and its duration for a motion token. A motion's `interrupt` now switches back to its `from` state at that time in `motion shots`.
+- `design sketch` merges a sketch of a base part into the base. `sketch new --override` opens a product override; `--into-base` moves an existing override into the base. `sketch ready` refuses a variant that does not load.
+- Add `design sketch hold <sketch> --until <text>` and `design sketch release <sketch>`: a held sketch goes back to in progress, leaves the merge queue, and `sketch ready` refuses with the `--until` text until it is released.
+- A sketch may carry an edit to a host of its target in a higher layer when the edit only changes the host's imports, so a rename across layers merges in one sketch.
+- `sketch ready` refuses a live variant whose files, or the `shared/` files they import, keep an unused import, parameter or CSS class.
+- Add `tokenSheet` to `@design-system`: it draws a foundations part as a sheet of its CSS custom properties, labelled with the values the drawing resolves, so every product draws its foundations the same way.
+- `design complete` checks the `button`, `select`, `menu`, `row` and `tooltip` control kinds and a declared `disabled` look, and reads a base part's review from its base's `merged.json`.
+- `design complete` fails a page as `INVENTORY-UNAPPROVED` until its control inventory is approved; the design server answers `/__design/inventory` and `/__design/inventory-approve`, which writes `inventory.json` and refuses pages with undeclared or unclassified controls.
+- `design complete` gives each control inside an embedded part's `data-et-part` root to that part, fails the host while that part is incomplete, and fails a host CSS rule restyling it as `CONTROL-OVERRIDDEN`.
+- `et design mcp` gains the tools `sketch_variant`, `sketch_round`, `sketch_list`, `sketch_check`, `sketch_preview`, `sketch_rebase` and `comment_reply`.
+
+### Patch Changes
+
+- `design complete` accepts an option named by `aria-activedescendant` as focus-visible evidence when it looks different from a plain option in its surface, and its gap says which evidence is missing.
+- `design complete --request <part>.<control>.<requirement> --reason` writes a pending exception that still fails. Studio's approve endpoint records by, at and the part hash; then the gap passes until the part changes.
+- `design complete <layer>/<name> --variant <key>` checks a variant of the part's open sketch, so a sketch proves it closes its gaps before it is merged.
+- `design complete`: a `data-et-control-part` descendant of a `data-et-control` takes the forced interactions of its control, and its `disabled` or `aria-disabled="true"` counts as the control's disabled mark.
+- `et design complete <part> --handoff` gives a design complete part the `handoff` status; `et design complete --handoff` re-checks every `handoff` part and exits 1 when one regressed, for CI.
+- `design` renders no longer fail with "exports is not defined": the CLI build again ships the frame runtime as source only, with no CommonJS copies next to it.
+- `STALE-REPLACE` no longer warns on a `.replace` of markup a package draws, such as `button(options)` from `@ethlete/components`, which the rule cannot read.
+- `tokenSheet` styles now carry static fallbacks for every custom property, so design products without the Studio tokens draw a sane sheet.
+- `tokenSheet` takes `scope`, classes on the sheet root where values are read, so theme-scoped tokens resolve, and `note`, markup drawn under the title.
+- A design frame retries a failed part import twice after a short back-off, so a part file that changes while its grid loads no longer leaves "Failed to fetch dynamically imported module" in the frame.
+
+## 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;
     });
   };
 
@@ -248,6 +245,49 @@ 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.
+ */
+export const fitOutOfFlow = (root: HTMLElement, options: { sideways: boolean }) => {
+  const view = root.ownerDocument.defaultView;
+
+  if (!view) return;
+
+  const box = root.getBoundingClientRect();
+  const style = view.getComputedStyle(root);
+  const fillsViewport = (style: CSSStyleDeclaration) =>
+    style.position === 'fixed' &&
+    [style.top, style.right, style.bottom, style.left].every((edge) => parseFloat(edge) === 0);
+  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())
+    .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)));
+    const [before, after] = paddings.map((padding) => parseFloat(padding) || 0) as [number, number];
+
+    if (extent === 0) return '';
+
+    return `${style.boxSizing === 'border-box' ? extent + after : extent - before}px`;
+  };
+
+  root.style.minHeight = extentOf({
+    side: 'bottom',
+    start: box.top,
+    paddings: [style.paddingTop, style.paddingBottom],
+  });
+  if (options.sideways)
+    root.style.minWidth = extentOf({
+      side: 'right',
+      start: box.left,
+      paddings: [style.paddingLeft, style.paddingRight],
+    });
+};
+
 /** Types a drawing where it is written, so a mistake reads in its own file and not in `call.ts`. */
 export const drawing = (drawn: Drawing): Drawing => drawn;
 

package/design/define-part.ts

@@ -1,14 +1,21 @@
 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';
 export type { EmbedPageOptions } from './embed-page';
+export { iconSheet } from './icon-sheet';
+export type { IconSheetIcon, IconSheetOptions } from './icon-sheet';
 export { interactionRows } from './interaction-rows';
 export type { InteractionRowsOptions } from './interaction-rows';
+export { spring } from './spring';
+export type { Spring } from './spring';
 export { svgAsset } from './svg-asset';
 export type { SvgAssetOptions } from './svg-asset';
+export { tokenSheet } from './token-sheet';
+export type { TokenSheetOptions } from './token-sheet';
 
 /** An interaction Studio can force on a part's root element. Rest is always drawn and never listed. */
 export type Interaction = 'hover' | 'focus-visible' | 'active' | 'disabled';
@@ -23,9 +30,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 +46,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 +89,61 @@ 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 and active (a `field` needs no active), `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}`;
+
+/**
+ * What a control of each `kind` needs besides the interactions of its `input`. A surface is the element marked
+ * `data-et-surface="<id>.<surface>"`, drawn visible and filled in the state its `surfaces` entry names.
+ * - `disclosure`: a state that draws it collapsed, and `surfaces.body`.
+ * - `button`: `active`.
+ * - `field`: a text field (`<input>` or `<textarea>`); nothing beyond its inputs.
+ * - `select`, `menu`: `surfaces.open`, and options in it (`role="option"`, `role="menuitem"` or `data-et-option`)
+ *   drawn hovered, focus-visible, and selected with a look of their own.
+ * - `row`: drawn selected (`aria-selected`, `aria-checked`, `aria-pressed` or `aria-current`) with a look of its own,
+ *   and hovered while selected.
+ * - `tooltip`: `surfaces.tooltip`, the visible tooltip next to the control in this part.
+ *
+ * `disabled: true` also requires a state that draws it disabled with a look of its own. With `part`, the
+ * interactions, selected and disabled looks and option states come from that part, which must be design complete
+ * itself; the surfaces stay with this part. A page control needs `part`. With `input`, a state of this part draws
+ * each requirement, e.g. with `forceInteraction`.
+ */
+export type Control<TState extends string = string> = (
+  | { kind: 'disclosure'; surfaces: { body: TState } }
+  | { kind: 'button' | 'row' | 'field'; surfaces?: never }
+  | { kind: 'select' | 'menu'; surfaces: { open: TState } }
+  | { kind: 'tooltip'; surfaces: { tooltip: TState } }
+) & { disabled?: boolean } & ({ 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/embed-page.ts

@@ -2,9 +2,20 @@ import { Drawing } from './define-call';
 
 /**
  * How a page embeds another: the `state` to draw, the viewport `width` and `height` it is drawn at (`'auto'` grows
- * the frame to the page's content), and the `scale` the frame is shown at.
+ * the frame to the page's content), and the `scale` the frame is shown at. Inside the embedded page, `mark` rings
+ * every element matching its selector (each gets `data-et-embed-marked`), and `css` is added as a stylesheet.
  */
-export type EmbedPageOptions = { state?: string; width?: number; height?: number | 'auto'; scale?: number };
+export type EmbedPageOptions = {
+  state?: string;
+  width?: number;
+  height?: number | 'auto';
+  scale?: number;
+  mark?: string;
+  css?: string;
+};
+
+const MARK_CSS =
+  '[data-et-embed-marked] { outline: 0.2rem solid var(--et-theme-color-primary-solid, Highlight); outline-offset: 0.2rem; }';
 
 const KEPT = ['product', 'sketch', 'variant', 'surface', 'color'];
 
@@ -33,11 +44,12 @@ const attribute = (text: string) => text.replace(/&/g, '&').replace(/"/g, '&
  * Put the answer's `body` into the page's markup; it needs no styles or setup.
  */
 export const embedPage = (page: `pages/${string}`, options: EmbedPageOptions = {}): Drawing => {
-  const { state = 'default', width = 1280, height = 800, scale = 1 } = options;
+  const { state = 'default', width = 1280, height = 800, scale = 1, mark, css } = options;
   const search = embedSearchOf({ page, state, current: globalThis.location?.search ?? '' });
   const auto = height === 'auto';
   const frameHeight = auto ? 0 : height;
-  const frame = `<iframe data-et-embed="${attribute(page)}" data-et-embed-scale="${scale}"${auto ? ' data-et-embed-height="auto"' : ''} title="${attribute(page)}" src="/frame.html?${attribute(search)}" style="display:block;border:0;width:${width}px;height:${frameHeight}px;transform:scale(${scale});transform-origin:0 0"></iframe>`;
+  const inside = `${mark ? ` data-et-embed-mark="${attribute(mark)}"` : ''}${css ? ` data-et-embed-css="${attribute(css)}"` : ''}`;
+  const frame = `<iframe data-et-embed="${attribute(page)}" data-et-embed-scale="${scale}"${auto ? ' data-et-embed-height="auto"' : ''}${inside} title="${attribute(page)}" src="/frame.html?${attribute(search)}" style="display:block;border:0;width:${width}px;height:${frameHeight}px;transform:scale(${scale});transform-origin:0 0"></iframe>`;
 
   return {
     body:
@@ -68,3 +80,24 @@ export const fitEmbed = (embed: Element | null, height: number) => {
 
   frame.dataset['etEmbedDrawn'] = '';
 };
+
+/**
+ * Called by an embedded frame after it draws and on each change of its content: adds the `css` of its `embedPage`
+ * once and marks every element in `root` that matches its `mark`. Does nothing in a frame no page embeds.
+ */
+export const applyEmbed = (embed: Element | null, root: HTMLElement) => {
+  if (!(embed as HTMLElement | null)?.hasAttribute('data-et-embed')) return;
+
+  const { etEmbedMark: mark, etEmbedCss: css } = (embed as HTMLElement).dataset;
+  const document = root.ownerDocument;
+
+  if ((mark || css) && !document.querySelector('style[data-et-embed-css]')) {
+    const style = document.createElement('style');
+
+    style.dataset['etEmbedCss'] = '';
+    style.textContent = `${mark ? MARK_CSS : ''}\n${css ?? ''}`;
+    document.head.append(style);
+  }
+
+  if (mark) for (const element of root.querySelectorAll(mark)) element.setAttribute('data-et-embed-marked', '');
+};

package/design/icon-sheet.ts

@@ -0,0 +1,151 @@
+import { Drawing, html } from './define-call';
+import { svgAsset } from './svg-asset';
+
+export type IconSheetIcon = {
+  name: string;
+  svg: string;
+  grid?: number;
+  padding?: number;
+};
+
+export type IconSheetOptions = {
+  view: 'catalogue' | 'construction';
+  title: string;
+  note?: string;
+  icons: IconSheetIcon[];
+  sizes?: number[];
+  size?: number;
+  columns?: number;
+};
+
+const SHEET_STYLES = `
+  .ics-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); }
+  .ics-root svg { display: block; }
+  .ics-title { margin: 0; font-size: var(--text-xl, 1.7rem); line-height: var(--text-xl-line, 2.2rem); font-weight: var(--weight-strong, 600); }
+  .ics-note { margin: 0; max-width: 64rem; color: var(--text-muted, oklch(0.72 0 0)); }
+  .ics-group { margin: 0; font-size: var(--text-lg, 1.5rem); line-height: var(--text-lg-line, 2rem); font-weight: var(--weight-strong, 600); }
+  .ics-muted { color: var(--text-muted, oklch(0.72 0 0)); }
+  .ics-name { justify-self: start; font-family: var(--font-code, ui-monospace, "SF Mono", Menlo, Consolas, monospace); color: var(--text-muted, oklch(0.72 0 0)); }
+  .ics-catalogue { display: grid; align-items: center; justify-items: center; column-gap: var(--space-4, 1.6rem); row-gap: var(--space-2, 0.8rem); }
+  .ics-size { font-size: var(--text-sm, 1.15rem); }
+  .ics-cell { display: flex; }
+  .ics-construction { display: grid; gap: var(--space-5, 2rem); }
+  .ics-item { display: flex; flex-direction: column; align-items: center; gap: var(--space-2, 0.8rem); }
+  .ics-frame { position: relative; display: flex; border: 1px solid var(--surface-border, oklch(0.34 0 0)); background: var(--surface, oklch(0.17 0 0)); }
+  .ics-icon { position: relative; }
+  .ics-guides { position: absolute; inset: 0; width: 100%; height: 100%; color: var(--accent, oklch(0.7 0.15 250)); pointer-events: none; }
+  .ics-guides path, .ics-guides rect { vector-effect: non-scaling-stroke; stroke-width: 1px; }
+  .ics-pixels { opacity: 0.18; }
+  .ics-key { opacity: 0.7; stroke-dasharray: 4 3; }
+`;
+
+const VIEW_BOX = /\bviewBox\s*=\s*["']\s*[-\d.]+[\s,]+[-\d.]+[\s,]+([\d.]+)[\s,]+([\d.]+)/u;
+
+const gridOf = (icon: IconSheetIcon) => {
+  if (icon.grid) return icon.grid;
+  const [, width, height] = VIEW_BOX.exec(icon.svg) ?? [];
+  if (!width || !height) throw new Error(`iconSheet: "${icon.name}" has no viewBox, so it needs a grid`);
+
+  return Math.max(Number(width), Number(height));
+};
+
+const groupsOf = (icons: IconSheetIcon[]) => {
+  const groups = new Map<number, IconSheetIcon[]>();
+  for (const icon of icons) groups.set(gridOf(icon), [...(groups.get(gridOf(icon)) ?? []), icon]);
+
+  return [...groups];
+};
+
+const gridLabel = (grid: number) => (grid <= 48 ? `${grid} px grid` : `${grid}-unit grid`);
+
+const guides = (grid: number, { cls, paths }: { cls: string; paths: string }) =>
+  `<svg class="ics-guides ${cls}" viewBox="0 0 ${grid} ${grid}" fill="none" stroke="currentColor" aria-hidden="true" data-grid="${grid}">${paths}</svg>`;
+
+const pixelLines = (grid: number) => {
+  const step = grid > 48 ? grid / 16 : 1;
+  const lines = Array.from({ length: Math.round(grid / step) - 1 }, (_, index) => (index + 1) * step);
+
+  return guides(grid, {
+    cls: 'ics-pixels',
+    paths: lines.map((at) => `<path d="M${at} 0V${grid}M0 ${at}H${grid}"/>`).join(''),
+  });
+};
+
+const keyLines = (grid: number, padding: number) =>
+  guides(grid, {
+    cls: 'ics-key',
+    paths: `<path d="M${grid / 2} 0V${grid}M0 ${grid / 2}H${grid}"/><rect x="${padding}" y="${padding}" width="${grid - 2 * padding}" height="${grid - 2 * padding}"/>`,
+  });
+
+const drawIcon = (icon: IconSheetIcon, { size, cls }: { size: number; cls?: string }) =>
+  svgAsset(icon.svg, { size, class: cls, attrs: { 'aria-hidden': 'true' } });
+
+const catalogue = (icons: IconSheetIcon[], sizes: number[]) =>
+  html`<div
+    class="ics-catalogue"
+    style="grid-template-columns: max-content repeat(${sizes.length}, minmax(var(--space-7, 3.2rem), max-content))"
+  >
+    <span></span>
+    ${sizes.map((size) => html`<span class="ics-size ics-muted">${size} px</span>`).join('')}
+    ${icons
+      .map(
+        (icon) =>
+          html`<span class="ics-name">${icon.name}</span>${sizes
+              .map((size) => html`<span class="ics-cell">${drawIcon(icon, { size })}</span>`)
+              .join('')}`,
+      )
+      .join('')}
+  </div>`;
+
+const construction = (
+  icons: IconSheetIcon[],
+  { grid, size, columns }: { grid: number; size: number; columns: number },
+) =>
+  html`<div class="ics-construction" style="grid-template-columns: repeat(${columns}, max-content)">
+    ${icons
+      .map(
+        (icon) =>
+          html`<div class="ics-item">
+            <span class="ics-frame"
+              >${pixelLines(grid)}${drawIcon(icon, { size, cls: 'ics-icon' })}${keyLines(grid, icon.padding ?? grid / 8)}</span
+            >
+            <span class="ics-name">${icon.name}</span>
+          </div>`,
+      )
+      .join('')}
+  </div>`;
+
+/**
+ * Draws a foundation sheet of icons. `catalogue` shows every icon at each of `sizes` with its name; `construction` shows
+ * each icon `size` px large on its grid, with the grid lines, the centre lines and the padding box. An icon's grid is its
+ * `grid`, else the larger side of its viewBox; its padding is `padding` grid units, `grid / 8` by default.
+ * Icons on different grids are drawn in one group per grid.
+ */
+export const iconSheet = ({
+  view,
+  title,
+  note,
+  icons,
+  sizes = [16, 24, 32],
+  size = 96,
+  columns = 5,
+}: IconSheetOptions): Drawing => {
+  const groups = groupsOf(icons);
+  const labelled = groups.length > 1;
+
+  return {
+    body: html`<div class="ics-root">
+      <h2 class="ics-title">${title}</h2>
+      ${note && html`<p class="ics-note">${note}</p>`}
+      ${groups
+        .map(
+          ([grid, members]) =>
+            html`${labelled && html`<h3 class="ics-group">${gridLabel(grid)}</h3>`}${
+              view === 'catalogue' ? catalogue(members, sizes) : construction(members, { grid, size, columns })
+            }`,
+        )
+        .join('')}
+    </div>`,
+    styles: SHEET_STYLES,
+  };
+};