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

package/CHANGELOG.md

@@ -1,5 +1,203 @@
 # @ethlete/cli
 
+## 3.0.0-next.23
+
+### Minor Changes
+
+- `et design shot --variants --crop changed` cuts every cell to one box around the pixels the shown variants change from the merged part, and prints that box for a later `--crop`.
+- Add `@ethlete/cli/playwright/failure-reporter`, a Playwright reporter that writes one JSON line per failed test attempt while the run goes on.
+- The Playwright failure reporter writes a `detail` field: the first line past the kept error lines that holds a URL or a diff line, so a refused request stays visible.
+- Reject and reopen single sketch variants with `et design sketch reject|reopen` or in Studio; a rejected variant keeps its reason, origin and history and can no longer be picked or merged.
+- Studio's sketch view gets a "Changed area" switch per round that shows every column cropped to the one area the round's variants change, enlarged, under a small whole-page thumbnail, and the design server answers that area on `/__design/sketch-crop`.
+
+### Patch Changes
+
+- `et design` commands that render Angular markup now exit after they print their result.
+- A sketch state whose markup differs or only renders in a browser now counts as unchanged when its pictures match the product. Studio folds such states and shows a count with a "Show all states" button.
+- `design shot --state <s> --variants` shows a neutral "New state - no merged version" cell when only the variants have the state, instead of a red render error.
+- `et design shot --variants` takes `--round <key>` and `--variant <name>` to draw only the current round next to the merged row.
+- A design check now reports a type checker that failed without output as `NO-TYPE-CHECKER`, with the command and the process error, instead of an empty `TYPE-ERROR`.
+
+## 3.0.0-next.22
+
+### Major Changes
+
+- Every agent write in `et design` (`sketch new|report|ready|rebase|merge|discard`, `inbox done`, `comment reply`) needs `--by <model id>`. `sketch report` takes `--variant`, records authors per variant in `sketch.json`, and a merge writes them into the part's `madeBy`.
+
+### Minor Changes
+
+- Design comments have an addressed state: the agent and the cli mark a thread addressed, and only the user resolves it in Studio.
+- `design check` and Studio warn of a merged part whose files changed outside a sketch.
+- A design comment takes an `interaction` (rest by default, also `--interaction` on `et design comment`); a comment file without one is on rest.
+- `et design comment reply --question` marks a reply that waits for the user. Comments carry a `threadState` (`agent`, `question` or `answered`) in the Studio API and `inbox --json`.
+- Comment threads: `et design comment reply <id> <text>` answers a comment, and `et design inbox` lists threads where the agent spoke last under "waiting for the user".
+- A design comment stores `size` (a preset name, a width or `fitted`) in place of `preset`, `et design comment` takes `--size`, and the design server signals comment changes on `/__design/comment-events`.
+- Rule `FLOW` accepts a frame that names a page existing only as an open sketch, checked against the states of the sketch's first variant. A name that exists nowhere still fails.
+- Read a product's flows from `flows/<name>.json`, list them at `/__design/flows`, and fail `et design check` on a flow frame that names a missing state.
+- The design server reloads only the frames of a part whose file was added or removed, and `et design inbox done --by` now records the id in the variant's authors or the part's `madeBy`.
+- BREAKING: `et design inbox done <id>` now needs `--note "<reason>"`, which replaces the part's note; Studio withdraws a comment through the new `comment-withdraw`.
+- Rule `WIREFRAME-KIT` lets an element import the wireframe kit, so a rough shell can be an element the pages import. Components and foundations still may not.
+- The design server marks each part's root element with `data-et-part`, and `/__design/sketch-compare` draws every state that shows a sketched part before and after a merge, splits them by pixel change and returns the part's outlines.
+- `et design inbox` lists a sketch whose baseline is stale as "needs rebase", with the changed parts. A merge the design server refuses for a stale baseline answers with `changed` and the `rebase` command.
+- A pointed design note stores the `size` it was written at. `et design check` fails a pointed note without a size, or with a size the product no longer has.
+- A design part can list the `interactions` Studio draws it in, and a frame can force `:hover`, `:focus-visible`, `:active` or disabled on the part's root element through `interaction=<name>`.
+- `definePart` keeps a part's state names in its type, and `render` takes `{ interaction }` to force hover, focus-visible, active or disabled on the drawing's root.
+- A design part imports another part's stylesheet as `@system/<layer>/<name>.css?inline`, resolved per product and sketch, so base parts draw with a product's own tokens. A part that comes or goes redraws its whole product.
+- `GET /__design/system` lists for each part the pages that use it through the import graph, also in products that use its product as base.
+- A design part can declare container `widths`, and the shot route draws a part at a `width` or fitted to its content when the address names no preset.
+- The design server sends a `parts` event with the parts a file change redraws, per product and sketch variant, or `all`, and drops exactly those cached shots.
+- `et design product new <name>` creates a design product: its `config.json` entry and the empty layer folders. `--base` sets the base, and `--from-project` copies the render settings of a project.
+- `et design sketch variant <target> <name> --from <variant>` copies a variant into a new one and reopens the sketch; `sketch.json` groups variants into `rounds`, and `--round <title> --note <text>` starts a new round.
+- Sketch variants share code through `@shared/<path>`, `sketch new --like` copies a part or variant, and `embedPage()` draws a page inside a page.
+- The design server's sketch list carries the states and widths of the target as each variant draws it, and the agent's live report with the variant it names.
+- Pages can draw wireframes with the grey kit from `@design-system/kit` (box, text lines, image, button, input, icon); `et design check` fails a part outside pages that imports it, and the system list counts each page's kit calls.
+- `et design sketch check --fix` writes the variants in the checkout's Prettier format before it checks them; a FORMAT problem points to it.
+- `et design sketch check` warns of a variant that restyles a class of the sketch's `shared/` folder and of a variant file nothing imports.
+- `et design sketch new` takes `--variant-note`, `sketch variant` takes several variants, and sketch commands format their output, explain each flag and infer `--product`.
+- `et design sketch round` edits an existing round, and `sketch list` shows the rounds of each sketch.
+- The sketch listing for Studio names, per variant, the states it renders to the same markup and styles as the product does now (`unchanged`), cached by the part folder hashes.
+- `design check` warns of an export in a part's `shared/` that nothing imports, and `sketch check` of a sketch `shared/` export a variant does not import.
+- `sketch new --variant-note` keeps each variant's note in `sketch.json` instead of overwriting the part's merged note; Studio shows it in the variant's head, and a merge gives it to a new part.
+- A sketch variant may hold its own copy of a shared file at `<variant>/shared/<path>`: `@shared/<path>` resolves to it first in rendering, typechecks and checks, and a merge of that variant carries it.
+- The wireframe kit draws for narrow presets: a row `box` stacks below `stackBelow`, `image` takes a `ratio`, buttons and placeholders end with "…", boxes set the kit text colour, and `heading(text)` draws titles.
+- Add `et design accept <layer>/<name> --by <model id> --note <why>`, which records a direct edit of a merged part the user approved so `design check` stops warning of it.
+- `design shot --asset <file>` draws an image file into a PNG, and `design token <name> --hex` prints the colour a product token resolves to.
+- The design render check warns of grid rows that leave out interaction columns other rows fill (`GRID-COVERAGE`).
+- `et design check` also type-checks each variant of an open sketch and fails with a `TYPE-ERROR` line per broken variant. A merge's own check still types only the product.
+- `design check` and `design sketch check` draw every state headlessly and report `OVERFLOW`, `CLIPPED`, `WRAP`, `ZERO-SIZE` and `RENDER` problems. A part opts out with `definePart({ checks: { skip: [...] } })`.
+- `design check` warns of a `.replace` on markup that neither the part nor a part it uses draws (`STALE-REPLACE`).
+- The design render check warns of a class with a product prefix that no stylesheet of the frame defines (`UNDEFINED-CLASS`).
+- `et design sketch merge` now merges only the picked variant and refuses on parts changed since the sketch began (`sketch rebase` clears it); `check` flags stale notes and the system list carries product themes.
+- The `CLIPPED` render check also reports an outline (width plus offset) or a crisp outer box shadow (no blur) that passes the nearest clipping ancestor or the frame. A soft shadow with blur is not counted.
+- The `CLIPPED` render check also reports an underline (offset, thickness, and a wavy line's swing) that a clipping ancestor cuts off below the text.
+- `forceInteraction` from `@design-system` forces an interaction on one element of a part's markup, not only its root.
+- Every design frame loads its product's `foundations/tokens` stylesheet before the part's styles, so a part no longer imports the tokens itself.
+- A design frame and its shot take `fill=<token>`: the page paints its background with that token in place of the product's page fill.
+- The render check reads each drawn part's `grid`: `sketch check` prints `grid <rows> x <columns> ok` or the states it leaves out, and a state in two cells or a cell naming no state fails as `GRID`.
+- `interactionRows` from `@design-system` builds a part's states and grid from one props object per row and a list of interactions.
+- `et design serve` lists, writes, changes and deletes notes on states (`<product>/notes/<id>.json`) and free notes in a flow file's `notes`. A stale note now fails the check under rule `NOTE`; the flow rule checks free notes.
+- `et design part remove <layer>/<name>` deletes a merged part with its `merged.json` entry and tsconfig path, and resolves its comments. It refuses a part another part imports, a base part, and a part with an open sketch.
+- Design: hide inherited parts, clarify new-part merging, and protect parts imported by application source.
+- `definePart({ styles })` exposes a part's stylesheet on its default export and adds it to every drawing of the part.
+- POST `/__design/product` accepts `@ethlete/components` as `base`, like `--base @ethlete/components`.
+- The design server creates a product on POST `/__design/product` with `{ name, base? }`, using the code of `et design product new`. `base` names another product of the checkout.
+- A design server not started by Studio listens on a free port, so it never takes the port Studio expects.
+- The design server answers Studio's sketch and comment requests: it lists open sketches, previews a merge, writes a pick or discard, merges or discards a sketch, and lists, adds and finishes canvas comments.
+- The design server lists product systems, renders part states in frames and screenshots them. `et design system --json` prints the parts list.
+- `design shot <part> --states --variants --at <commit>` draws a sketch as that commit held it, so a merged sketch can be compared again.
+- Add `et design shot <layer>/<name> --states [--variants]`, which draws every state of a part and every variant of its open sketch into one labelled contact-sheet PNG and prints its path.
+- `et design sketch` opens, checks, merges and discards sketches of a part. `et design inbox` lists open comments and the user's sketch decisions.
+- `definePart` takes an optional `grid` that lays out small states as rows and columns, and `design shot --states` draws such a part one sheet row per grid row.
+- `svgAsset` sets a `class` and `attrs` on the root `<svg>` of an asset.
+- Add `svgAsset(raw, { size })` to `@design-system`, fail `design check` on an SVG asset without a root `<svg>` or the SVG namespace, print each variant's `assets/` folder, and add a pixel diff row to `design shot --variants`.
+- `et design` supports product design systems with layers, a base and presets. `et design check --product <name>` checks a product's layer rules, colours, component copies and motion.
+- The design render check reports `UNKNOWN-THEME` when a drawing uses a colour theme that no stylesheet of its frame defines.
+- A design part may export named helpers next to its `definePart` default, and other parts import them from `@system/<layer>/<name>`.
+- Closing a design comment thread (inbox done, a new sketch round, a merge or discard) now resolves it instead of deleting it, so it can be looked up later.
+- `sketch round --drops <state,state>` lets a round remove part states on purpose, so `sketch check` and `sketch ready` no longer fail those variants for the dropped states.
+- The design server answers `/__design/sketch-diff` with the box of the pixels a sketch variant changes per state against the merged part, cached per pair of pictures.
+
+### Patch Changes
+
+- `sketch ready` no longer fails its auto merge on a problem the product already had, and runs the check and the auto merge again on a sketch that is already ready.
+- `/__design/shot` also draws a call variant: `call`, `variant` and `width` give a full-height PNG at that width, kept until a file of the call changes.
+- `et design sketch check` reports an `@shared/` import that resolves to no file in the sketch's `shared/` folder.
+- Design parts and stylesheets load product assets as `@assets/<file>`.
+- `et design check --tsconfig` also typechecks each variant of an open sketch and prints the tsc output of a failing one.
+- Fix the type errors and lint errors of the design sources, write the editor tsconfig of each product while the design server runs, and update two stale design specs.
+- Design comments written in the same millisecond list in the order they were written.
+- The design server picks up changes to `.ethlete/design/config.json` while it runs, and keeps the last good config if the file becomes invalid.
+- A foundations part may import another foundations part, so a logo or an overview can draw with the product tokens. `et design check` still flags a foundation that imports a component, element or page.
+- The design server no longer reloads every frame page on each change; Studio redraws frames from the `parts` event.
+- `et design sketch variant` on a part with no open sketch names the `sketch new` command that starts one.
+- Cover a product stylesheet that registers its drawing folders with Tailwind `@source`, so page sketches compile the utilities the app uses.
+- `et design` copies its own code and frame assets into a per-process folder at start and serves them from there, so rebuilding or reinstalling the cli no longer changes what a running design server serves or renders.
+- `/__design/shot` answers a timeout or a build error with an error status, and `et design` picks up config changes without a restart.
+- `GET /__design/shot` answers 422 with the reason when the part root has zero size or the screenshot fails, instead of waiting out the 30 s Playwright timeout.
+- `et design sketch new` takes `--note <text>`, the note of the first round.
+- `design sketch new` scaffolds `definePart` without a type argument, so the part keeps its state names.
+- The design server's frame page and shot route draw a part as a sketch variant holds it when the address names `sketch` and `variant`.
+- `checks.skip` applies per sketch variant, and `data-et-skip` lets a drawn element opt out of a render check.
+- A design frame now loads its project or product stylesheets in config order, so the last sheet in `styles` always wins.
+- `et design <command> [<subcommand>] --help` prints the usage of that one command and skips its checks.
+- A design product can name several token parts in its config `tokens`; frames load each one's stylesheet in order.
+- `et design check` reports a `var(--token)` without a fallback that no part or stylesheet of the product or its base defines.
+- A design drawing may leave out `styles`: `drawing({ body })` is enough when `definePart({ styles })` carries the stylesheet, and a part's `render` still answers a string of styles.
+- Design: a frame page reports its viewport size with its height, and a frame fitted to its content never shows scrollbars.
+- A part's dependencies include the parts a plain module of its own folder imports, so `sketch check` lists a page that uses a part through such a module, and the rules see the import.
+- A design frame's height message carries its `href` and `errored: true` once the frame failed to draw or threw at runtime.
+- `design sketch check` and `sketch ready` no longer fail on an open comment whose sketch was merged or discarded; they warn and say to reply with `comment reply --by` or have the user resolve it in Studio.
+- `design check` no longer warns with GRID-COVERAGE about a grid row that fills only `rest`. It warns only about a row that fills some interaction columns but not all.
+- `et design sketch ready` names why it did not merge a sketch automatically: the changed states, a failed shot, or a variant that holds another part.
+- `et design sketch report --done` prints "<variant> marked done", also when the variant had no live report.
+- Design validation now checks tokens in reachable shared stylesheets.
+- `et design shot --crop x,y,width,height` and `/__design/shot?clip=x,y,width,height` cut a picture to a box in CSS pixels, so a hairline can be judged with `--scale`.
+- `et design shot --variants --diff-props` compares each variant with the merged part drawn with the variant's state props, so changed props no longer paint the whole diff red.
+- `et design shot --states --variants` lays out the merged row and each variant row by its own `grid`, with a diff row after each grid row.
+- `et design shot` without `--product` takes the only product with an open sketch on the part, else the only product with the part.
+- `et design shot --interaction <hover|focus-visible|active|disabled>` forces an interaction on every cell, and `--help` names it. The design-exploration skill names it.
+- The diff row of `et design shot --variants` says "no pixel change, but the markup differs" when a variant draws other markup to the same pixels.
+- A `/__design/shot` of a state the merged part or the variant lacks answers a 404 that names its states, instead of a 500 drawn as PNG.
+- A `/__design/shot` request without `state=` answers a 400 that names the part's states.
+- `et design shot --variants` on a part that is not merged yet heads the sheet with "new part, nothing to compare with".
+- The diff row of `et design shot --variants` names a state the merged part does not have as "new state", on the sheet and among the printed lines.
+- `et design shot` draws a non-page part with `widths` at its first width unless `--width` or `--preset` is given.
+- `et design shot` prints the PNG path after the diff lines.
+- `et design shot --scale <1-4>` and `/__design/shot?scale=` draw a part at a device scale, so a small part is legible. The design-exploration skill names it.
+- `et design shot --state <a>,<b>` draws only the named states, side by side, and names the states of the part when one does not exist. The design-exploration skill names it.
+- `sketch check` and `sketch ready` fail only on problems a variant brings in. A problem the product already had prints as `NOTE (was there before)`, as the merge does.
+- `sketch new` prints the next steps: `sketch report` while you draw a variant, `report --done` only after a report, the round note when it is missing, then `sketch check` and `sketch ready`.
+- `et design sketch new --round` requires `--note`, so `sketch ready` no longer stops on a round without a note.
+- `et design sketch variant` refuses a sketch the user discarded and asks for a variant pick first; a pick is still cleared.
+- The UNDEFINED-TOKEN check of `et design check` and `et design sketch check` also reads the stylesheets a part imports, and the tokens any file of the part folder sets.
+- The wireframe kit draws more control types: `select`, `tabs`, `segmented`, `checkbox`, `badge` and `dot`.
+- A wireframe kit `box` takes `fill: true` to be at least as tall as the frame, so a page or a shell needs no hand-written `min-height`.
+- A wireframe kit `icon` is a rounded square instead of a circle that read as a radio button, and takes a `glyph` name (`'plus'`, `'close'`, `'menu'`, …) drawn inside it.
+- Every `et design` command finds `.ethlete/design/config.json` in a parent folder, so a sketch report works from a subfolder.
+- Studio refreshes its frames when optimized dependencies change, preventing stale module links after part removal.
+- Write a gitignored `tsconfig.json` into `.ethlete/design` and each product folder so editors resolve `@design-system` and `@system/*`, typecheck products and sketch variants through one function, and lint the design frame sources.
+- The pixel diff of `design shot --variants` runs about 3.5 times faster.
+- The design server sends a `flows` event when a flow file changes, and Studio reads the flows again, so a flow edit shows without a server restart.
+- The design frame page posts `Esc` to its parent. The Studio canvas now leaves an active cross-origin frame on `Esc` and takes its height from the frame page.
+- `et design shot` and the render check take a free port even when 5173 is busy. Vite read port 0 as unset.
+- `et design sketch new pages/<name>` scaffolds a page like its siblings: the tokens import, `madeBy` from `--by`, the product widths and no stylesheet.
+- `et design product new --base` no longer writes an empty `fixtures.ts`, so the new product uses its base's fixture set.
+- `et design product new` writes `config.json` in the layout Prettier gives it, so a later format run leaves it unchanged.
+- The `CLIPPED` and `WRAP` render-check lines name their opt-out: `data-et-skip="<RULE>"` on the element, or `definePart({ checks: { skip: ['<RULE>'] } })`.
+- The design server's JSON answers allow any origin, so Studio can read the parts list.
+- The design server takes `--host <address>` (or `DE_HOST`) to listen on another address than localhost, e.g. `0.0.0.0` to reach it over the LAN.
+- `design shot --states --variants` prints the pixel result of each diff cell, and scales each diff cell to the width of its state cell.
+- The design server draws merge compares and plain `/__design/shot` asks before Studio's canvas shots, which now ask with `priority=low`.
+- `design sketch new` and `design sketch variant` create the `assets/` folder of each variant, so the path they print exists.
+- Design servers keep their own Vite cache per checkout, `design shot --variants` draws the merged state first, `sketch check` warns of a class two stylesheets of a part define, and `sketch ready` needs a note on the running round.
+- `et design inbox done --note` on a sketch thread now writes the note into the variant's copy of the part, never into the product.
+- A design merge that changes an asset re-records the other merged parts that use it, so they no longer show as changed outside a sketch, and lists them in the merge output.
+- `et design sketch merge` takes `--note` as optional and keeps the variant's own note without one; `sketch new`, `variant` and `ready` record `--by` as the variant author, and a merge no longer drops `madeBy`.
+- The `CLIPPED` render check measures a scaled `embedPage` at its scaled size, so a page that embeds a scaled page no longer needs `checks: { skip: ['CLIPPED'] }`.
+- A failed design shot answers 500 with the error picture, a shot accepts a preset with its own width, and sketch check lists every drawn state with its result.
+- `et design sketch check` and `sketch ready` now run the checkout's own Prettier over a variant and report each unformatted file, so an unformatted variant can no longer become ready or merge.
+- A sketch merge or discard closes the open comments on its variants instead of refusing, and `sketch variant --round` closes those on its `--from` variant.
+- A comment on a sketch variant now stores the `createdAt` of its sketch, so a later sketch on the same target no longer takes over, addresses or lists the comments of an earlier one.
+- Design sketches compare fresh screenshots instead of reusing pixel results from earlier rendering sessions.
+- `et design sketch check` and `sketch ready` fail when a variant drops a state the product's part has.
+- Sketch checks now flag targets whose metadata cannot be written during merge.
+- `design sketch new` on a merged part with a `shared/` folder moves that folder into the sketch's `shared/` and imports it as `@shared/`, so the variants no longer each hold a copy.
+- `design sketch new` and `sketch variant` print the repo-relative path of each variant's part file.
+- `et design sketch ready` merges a sketch by itself when no state of any variant differs by a pixel from the product, and logs it as `auto` in `accepted.json`.
+- `design sketch ready` compares pixels when a state's markup differs, so a sketch that only changes whitespace in the markup counts as unchanged.
+- `design sketch report` prints a confirmation, and refuses a sketch that is not in progress with a non-zero exit instead of recording a report Studio never shows.
+- `sketch report --variant <key> --done` ends the live "drawing" report of that variant, so Studio shows its frames before `sketch ready`. The design exploration skill names the command.
+- `sketch variant --round` stores why the running round lost in its own `lost` field instead of overwriting the round's note, and `--round-note` sets the new round's note so `sketch ready` accepts it.
+- Studio now folds a sketch state whose styles changed but whose frames draw the same pixels, so CSS a variant adds for one state no longer unfolds every other state.
+- `design sketch variant` without `--round` now fails while the sketch has open comments. It lists them and names the `--round` command, so an answer to comments starts a new round.
+- A design server no longer outlives a Studio that dies without a clean exit.
+- Remove the host commands only the old Calls view used: call statuses, verdicts, modes, closed states, new variants and check receipts.
+- Restore the host command that reports sketch report changes, so a drawing agent's progress reaches Studio live again.
+- Prevent macOS WebKit freezes when design frames reload, and keep previous content visible while asynchronous drawings finish loading.
+- Design check warns about unscoped selectors in globally loaded token stylesheets.
+- Studio no longer folds a sketch state as unchanged after the sketch's `shared/` folder or the variant's assets or fixtures change: the unchanged-states cache now keys on them too.
+- Update all dependencies to their latest versions (Nx 24, Vitest 5, jsdom 30, ts-morph 28, @types/node 26 and others). The optional `@nx/devkit` peer dependency now requires `^24.0.0`, and the optional `ts-morph` peer of `@ethlete/core` requires `^28.0.0`.
+
 ## 3.0.0-next.21
 
 ### Minor Changes

package/design/assets.d.ts

@@ -0,0 +1,9 @@
+declare module '@assets/*?raw' {
+  const text: string;
+  export default text;
+}
+
+declare module '@assets/*' {
+  const url: string;
+  export default url;
+}

package/design/define-call.ts

@@ -9,8 +9,13 @@ const flatten = (value: unknown): string => {
   return String(value);
 };
 
-const join = (strings: TemplateStringsArray, values: unknown[]) =>
-  strings.reduce((out, part, index) => out + flatten(values[index - 1]) + part);
+const join = (strings: TemplateStringsArray, values: unknown[]) => {
+  let out = strings[0] ?? '';
+
+  for (let index = 1; index < strings.length; index++) out += flatten(values[index - 1]) + strings[index];
+
+  return out;
+};
 
 /**
  * Marks a template literal as HTML, so Prettier formats it and an editor highlights it. It escapes
@@ -43,11 +48,13 @@ export type NgField = { value: unknown; errors?: (string | { kind: string; messa
 export type NgOptions = { imports?: string[]; fields?: Record<string, NgField> };
 
 const render = async (template: string, options: NgOptions) => {
+  const params = new URLSearchParams(location.search);
   const response = await fetch('/__design/render', {
     method: 'POST',
     headers: { 'content-type': 'application/json' },
     body: JSON.stringify({
-      call: new URLSearchParams(location.search).get('call') ?? '',
+      call: params.get('call') ?? '',
+      product: params.get('product') ?? undefined,
       template,
       imports: options.imports ?? [],
       fields: options.fields,
@@ -70,14 +77,14 @@ export const ng = async (template: string, options: NgOptions = {}) => {
 };
 
 /** A click on an element that matches `click` inside the drawing shows the state `go`. */
-export type StateRule<S extends string> = { click: string; go: S };
+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.
  */
 export const switchStates =
-  <S extends string>(states: Record<S, string>, rules: StateRule<S>[]) =>
+  <TState extends string>(states: Record<TState, string>, rules: StateRule<TState>[]) =>
   (root: HTMLElement) => {
     const host = root.querySelector<HTMLElement>('[data-de-states]');
 
@@ -107,11 +114,11 @@ export const switchStates =
  * Renders each named template with `ng()` and resolves with a `body` that shows the first state,
  * and `on(rules)`, a `setup` that swaps states on a click. Every state's styles load up front.
  */
-export const ngStates = async <S extends string>(templates: Record<S, string>, options: NgOptions = {}) => {
-  const names = Object.keys(templates) as S[];
+export const ngStates = async <TState extends string>(templates: Record<TState, string>, options: NgOptions = {}) => {
+  const names = Object.keys(templates) as TState[];
   const rendered = await Promise.all(names.map((name) => render(templates[name], options)));
   const states = Object.fromEntries(names.map((name, index) => [name, rendered[index]?.markup ?? ''])) as Record<
-    S,
+    TState,
     string
   >;
   const first = names[0];
@@ -124,18 +131,18 @@ export const ngStates = async <S extends string>(templates: Record<S, string>, o
         rendered.flatMap((entry) => entry.styles),
         emitted,
       ) + `<div data-de-states="${first}" style="display: contents">${states[first]}</div>`,
-    on: (rules: StateRule<S>[]) => switchStates(states, rules),
+    on: (rules: StateRule<TState>[]) => switchStates(states, rules),
   };
 };
 
 /**
  * One drawn answer, as the frame renders it: the markup that goes in the frame root, and the CSS
- * that styles it. `setup` is a function or a list of them, run in order once after the markup is in the frame root, to wire behavior such
+ * that styles it, left out when `definePart({ styles })` carries it. `setup` is a function or a list of them, run in order once after the markup is in the frame root, to wire behavior such
  * as a click that restarts an animation. A `<script>` in `body` never runs.
  */
 export type Drawing = {
   body: string;
-  styles: string;
+  styles?: string;
   setup?: ((root: HTMLElement) => void) | ((root: HTMLElement) => void)[];
 };
 
@@ -300,6 +307,8 @@ export type Call = {
   stage?: CallStage;
   /** Set by `et design legacy` on a call made before the stage was required. Such a call needs no stage. */
   legacy?: true;
+  /** Set by Ethlete Studio once the call was carried over into a product's design system. */
+  transferred?: true;
   /** Set once the call is done for good: `shipped` when the app implements it, `superseded` when another call replaced it. */
   closed?: 'shipped' | 'superseded';
   /** The slug of the call this one is parked on. The call is on hold until that call settles. */

package/design/define-part.ts

@@ -0,0 +1,102 @@
+import { Drawing } from './define-call';
+import { forceBody } from './mark-part';
+
+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 { interactionRows } from './interaction-rows';
+export type { InteractionRowsOptions } from './interaction-rows';
+export { svgAsset } from './svg-asset';
+export type { SvgAssetOptions } from './svg-asset';
+
+/** 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';
+
+/**
+ * One part of a product's design system. `note` records why the part has its current shape, and
+ * `madeBy` the model ids that drew it, written by a sketch merge.
+ * `states` names each state it is drawn in with the props for that state, and `render` draws it.
+ * `styles` is the part's stylesheet: every drawing of the part gets it before the styles `render` returns, and a
+ * host that embeds a piece of the part's markup takes it from the default export.
+ * A part that responds to its width lists the container `widths` it is drawn at; without them a
+ * 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`.
+ * `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.
+ */
+export type Part<TProps, TState extends string = string> = {
+  note: string;
+  madeBy?: string[];
+  states: Record<TState, TProps>;
+  styles?: string;
+  widths?: number[];
+  interactions?: Interaction[];
+  grid?: StateGrid<TState>;
+  checks?: { skip?: RenderCheck[] };
+  render: (props: TProps, options?: RenderOptions) => DrawnPart | Promise<DrawnPart>;
+};
+
+/** 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 };
+
+/**
+ * Small states laid out as one table instead of a frame each: `rows` maps a row label to the state drawn under
+ * each of the `columns`, and a missing column leaves its cell empty. States it leaves out are drawn as before.
+ */
+export type StateGrid<TState extends string = string, TColumn extends string = string> = {
+  columns: readonly TColumn[];
+  rows: Record<string, Partial<Record<TColumn, TState>>>;
+};
+
+/** 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';
+
+/** 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: Record<TState, NoInfer<TProps>>;
+  grid?: { columns: readonly TColumn[]; rows: Record<string, Partial<Record<NoInfer<TColumn>, NoInfer<TState>>>> };
+  render: (props: TProps) => Drawing | Promise<Drawing>;
+};
+
+/**
+ * Forces `interaction` on the first element of `markup`, as a frame forces it on a part's root: for a state that
+ * shows one element of the part, such as a row of a list, hovered or disabled.
+ */
+export const forceInteraction = (markup: string, interaction: Interaction) => forceBody(markup, interaction);
+
+const finished = (
+  drawn: Drawing,
+  { styles, interaction }: { styles?: string; interaction?: Interaction },
+): DrawnPart => ({
+  ...drawn,
+  body: interaction ? forceBody(drawn.body, interaction) : drawn.body,
+  styles: [styles, drawn.styles].filter(Boolean).join('\n'),
+});
+
+/**
+ * Types a part where it is written. A part file default-exports the result, and may export named
+ * helpers next to it that other parts import from `@system/<layer>/<name>`. Without type
+ * arguments, `TProps` comes from the props `render` takes and the state names stay in the type, so
+ * `part.states['open']` is `TProps` and an unknown name does not compile.
+ */
+export const definePart = <TProps, const TState extends string = string, const TColumn extends string = string>(
+  part: PartSource<TProps, TState, TColumn>,
+): Part<TProps, TState> => ({
+  ...part,
+  render: (props, options) => {
+    const drawn = part.render(props);
+    const interaction = options?.interaction;
+
+    return drawn instanceof Promise
+      ? drawn.then((done) => finished(done, { styles: part.styles, interaction }))
+      : finished(drawn, { styles: part.styles, interaction });
+  },
+});

package/design/embed-page.ts

@@ -0,0 +1,70 @@
+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.
+ */
+export type EmbedPageOptions = { state?: string; width?: number; height?: number | 'auto'; scale?: number };
+
+const KEPT = ['product', 'sketch', 'variant', 'surface', 'color'];
+
+/** The frame address of `page` in `state`, in the product, sketch variant and theme of the frame at `current`. */
+export const embedSearchOf = (options: { page: string; state: string; current: string }) => {
+  const current = new URLSearchParams(options.current);
+  const search = new URLSearchParams();
+
+  for (const key of KEPT) {
+    const value = current.get(key);
+
+    if (value !== null) search.set(key, value);
+  }
+
+  search.set('part', options.page);
+  search.set('state', options.state);
+
+  return search.toString();
+};
+
+const attribute = (text: string) => text.replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;');
+
+/**
+ * Draws another page of the product inside a page, in a frame of its own, so a page shows a page in context without
+ * importing it. The embedded page draws as the embedding frame does: the same product, sketch variant and theme.
+ * 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 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>`;
+
+  return {
+    body:
+      scale === 1
+        ? frame
+        : `<div data-et-embed-box style="overflow:hidden;width:${width * scale}px${auto ? '' : `;height:${frameHeight * scale}px`}">${frame}</div>`,
+    styles: '',
+  };
+};
+
+/**
+ * Called by an embedded frame each time it measures itself: marks its iframe drawn and, for `height: 'auto'`, grows
+ * the iframe (and the box of a scaled one) to `height`. Does nothing in a frame no page embeds.
+ */
+export const fitEmbed = (embed: Element | null, height: number) => {
+  if (!(embed as HTMLElement | null)?.hasAttribute('data-et-embed')) return;
+
+  const frame = embed as HTMLElement;
+
+  if (frame.dataset['etEmbedHeight'] === 'auto') {
+    frame.style.height = `${height}px`;
+
+    const box = frame.parentElement;
+
+    if (box?.hasAttribute('data-et-embed-box'))
+      box.style.height = `${height * Number(frame.dataset['etEmbedScale'] ?? 1)}px`;
+  }
+
+  frame.dataset['etEmbedDrawn'] = '';
+};

package/design/interaction-rows.ts

@@ -0,0 +1,32 @@
+export type InteractionRowsOptions<TProps, TInteraction extends string> = {
+  interactions: readonly TInteraction[];
+  force: (props: TProps, interaction: TInteraction) => TProps;
+};
+
+type RowState<TRow extends string, TInteraction extends string> = TRow | `${TRow}-${TInteraction}`;
+
+/**
+ * Builds the `states` and `grid` of a part from one props object per row: each row is drawn at rest as `<row>` and
+ * in each of `interactions` as `<row>-<interaction>`, with the props `force` returns. Spread the result into
+ * `definePart`; the built state names stay in its type.
+ */
+export const interactionRows = <TProps, const TRow extends string, const TInteraction extends string>(
+  rows: Record<TRow, TProps>,
+  { interactions, force }: InteractionRowsOptions<TProps, TInteraction>,
+) => {
+  const entries = Object.entries(rows) as [TRow, TProps][];
+  const states = Object.fromEntries(
+    entries.flatMap(([row, props]) => [
+      [row, props],
+      ...interactions.map((interaction) => [`${row}-${interaction}`, force(props, interaction)]),
+    ]),
+  ) as Record<RowState<TRow, TInteraction>, TProps>;
+  const gridRows = Object.fromEntries(
+    entries.map(([row]) => [
+      row,
+      Object.fromEntries([['rest', row], ...interactions.map((interaction) => [interaction, `${row}-${interaction}`])]),
+    ]),
+  ) as Record<TRow, Record<'rest' | TInteraction, RowState<TRow, TInteraction>>>;
+
+  return { states, grid: { columns: ['rest', ...interactions] as const, rows: gridRows } };
+};

package/design/mark-part.ts

@@ -0,0 +1,66 @@
+import { Drawing } from './define-call';
+import { Interaction, Part, RenderOptions } from './define-part';
+
+const SKIPPED = /^(?:\s+|<!--[\s\S]*?-->|<(style|script)\b[\s\S]*?<\/\1\s*>|<link\b[^>]*>)/i;
+const TAG = /^<[a-zA-Z][\w:-]*/;
+const ATTRIBUTES = /^(?:\s+[^\s"'>/=]+(?:\s*=\s*(?:"[^"]*"|'[^']*'|[^\s"'=<>`]+))?)*/;
+const MARK = /(\sdata-et-part=")([^"]*)"/;
+
+const attributesAtOf = (body: string) => {
+  let at = 0;
+
+  for (let skipped = SKIPPED.exec(body); skipped; skipped = SKIPPED.exec(body.slice(at))) at += skipped[0].length;
+
+  const tag = TAG.exec(body.slice(at));
+
+  return tag ? at + tag[0].length : null;
+};
+
+/** Adds `key` to `data-et-part` on the first element of `body`, after any leading styles, scripts, links and comments. */
+export const markBody = (body: string, key: string) => {
+  const attributesAt = attributesAtOf(body);
+
+  if (attributesAt === null) return body;
+
+  const attributes = ATTRIBUTES.exec(body.slice(attributesAt))?.[0] ?? '';
+  const marked = MARK.exec(attributes);
+
+  if (!marked) return `${body.slice(0, attributesAt)} data-et-part="${key}"${body.slice(attributesAt)}`;
+
+  const valueEnd = attributesAt + marked.index + (marked[1]?.length ?? 0) + (marked[2]?.length ?? 0);
+
+  return `${body.slice(0, valueEnd)} ${key}${body.slice(valueEnd)}`;
+};
+
+/** Forces `interaction` on the first element of `body` the way a frame forces it on the root of a part. */
+export const forceBody = (body: string, interaction: Interaction) => {
+  const attributesAt = attributesAtOf(body);
+
+  if (attributesAt === null) return body;
+
+  const forced = interaction === 'disabled' ? ' disabled aria-disabled="true"' : ` data-et-force="${interaction}"`;
+
+  return `${body.slice(0, attributesAt)}${forced}${body.slice(attributesAt)}`;
+};
+
+const markDrawing = <TDrawing extends Drawing>(drawn: TDrawing, key: string): TDrawing =>
+  typeof drawn?.body === 'string' ? { ...drawn, body: markBody(drawn.body, key) } : drawn;
+
+/** The part with a `render` that marks the first element of each drawing as the root of the part `key`. */
+export const markPart = <TProps, TState extends string>(
+  part: Part<TProps, TState>,
+  key: string,
+): Part<TProps, TState> => {
+  if (typeof part?.render !== 'function') return part;
+
+  const render = part.render;
+
+  return {
+    ...part,
+    render: (props: TProps, options?: RenderOptions) => {
+      const drawn = render.call(part, props, options);
+
+      return drawn instanceof Promise ? drawn.then((done) => markDrawing(done, key)) : markDrawing(drawn, key);
+    },
+  };
+};

package/design/svg-asset.ts

@@ -0,0 +1,36 @@
+const ROOT_SVG = /<svg\b(?:[^>"']|"[^"]*"|'[^']*')*>/u;
+
+export type SvgAssetOptions = { size: number | string; class?: string; attrs?: Record<string, string> };
+
+const escapeAttribute = (value: string) => value.replace(/&/gu, '&amp;').replace(/"/gu, '&quot;');
+
+const attributePattern = (name: string) =>
+  new RegExp(`\\s+${name.replace(/[.*+?^${}()|[\]\\]/gu, '\\$&')}\\s*=\\s*(?:"[^"]*"|'[^']*'|[^\\s/>]+)`, 'gu');
+
+/**
+ * Sets `width` and `height` of the root `<svg>` of a raw SVG asset (an `@assets/<file>.svg?raw` import) to `size`,
+ * keeping its `viewBox`, and sets `class` and `attrs` on it, replacing the asset's own. Throws when the string has
+ * no `<svg>` element.
+ */
+export const svgAsset = (raw: string, options: SvgAssetOptions) => {
+  const masked = raw.replace(/<!--[\s\S]*?-->/gu, (comment) => ' '.repeat(comment.length));
+  const root = ROOT_SVG.exec(masked);
+
+  if (!root) throw new Error('svgAsset: the asset has no <svg> element');
+
+  const set: Record<string, string> = {
+    width: String(options.size),
+    height: String(options.size),
+    ...(options.class === undefined ? {} : { class: options.class }),
+    ...options.attrs,
+  };
+  const rest = Object.keys(set).reduce(
+    (tag, name) => tag.replace(attributePattern(name), ''),
+    raw.slice(root.index + '<svg'.length, root.index + root[0].length),
+  );
+  const added = Object.entries(set)
+    .map(([name, value]) => ` ${name}="${escapeAttribute(value)}"`)
+    .join('');
+
+  return `${raw.slice(0, root.index)}<svg${added}${rest}${raw.slice(root.index + root[0].length)}`;
+};