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

package/CHANGELOG.md

@@ -1,5 +1,131 @@
 # @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
+
+- `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

package/design/define-call.ts

@@ -245,6 +245,75 @@ 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, 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;
+
+  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 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, 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)));
+    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

@@ -6,10 +6,18 @@ 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 { 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';
 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';
@@ -27,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;
@@ -44,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;
@@ -56,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> = {
@@ -83,21 +103,35 @@ 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. */
+/** 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}`;
 
 /**
- * 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`.
+ * 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 } } & (
-  { part: ControlPart; input?: never } | { input: ControlInput[]; part?: never }
-);
+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';

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,
+  };
+};

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,
+});