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

package/design/define-call.ts

@@ -29,15 +29,23 @@ export const html = (strings: TemplateStringsArray, ...values: unknown[]) => joi
 /** Marks a template literal as CSS, for the same reason `html` does it for markup. */
 export const css = (strings: TemplateStringsArray, ...values: unknown[]) => join(strings, values);
 
-const emitted = new Set<string>();
+const rendered = new Set<string>();
+const taken = new Set<string>();
 
-/** The `<style>` tags for the sheets not yet in `seen`, which it then records. */
-export const unseenStyles = (styles: string[], seen: Set<string>) => {
+/** The sheets in `styles` not yet in `seen`, which it then records, joined as one stylesheet. */
+export const unseenStyles = (styles: Iterable<string>, seen: Set<string>) => {
   const fresh = [...new Set(styles)].filter((style) => !seen.has(style));
 
   for (const style of fresh) seen.add(style);
 
-  return fresh.map((style) => `<style>${style}</style>`).join('');
+  return fresh.join('\n');
+};
+
+/** `drawn` with the component styles `ng()` rendered since the last drawing appended to its `styles`. */
+export const withNgStyles = <T extends Drawing>(drawn: T): T => {
+  const sdk = unseenStyles(rendered, taken);
+
+  return sdk ? { ...drawn, styles: [drawn.styles, sdk].filter(Boolean).join('\n') } : drawn;
 };
 
 /** A form field `ng()` builds: its value, the errors it shows (a kind, or a kind and a message), and whether it is touched. */
@@ -50,6 +58,9 @@ 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) => {
+  if (typeof location === 'undefined')
+    return { markup: template.replace(/<([a-zA-Z][\w:.-]*)/g, '<$1 data-et-ng'), styles: [] };
+
   const params = new URLSearchParams(location.search);
   const response = await fetch('/__design/render', {
     method: 'POST',
@@ -70,12 +81,15 @@ const render = async (template: string, options: NgOptions) => {
 
 /**
  * Renders an Angular template with the real components on the design server and resolves with its
- * markup, led by the component styles this frame has not received yet. Rejects with the render error.
+ * markup. The component styles go into the `styles` of the drawing the frame shows. Rejects with the render error.
+ * Outside a browser it resolves with the template unrendered, each element marked `data-et-ng`.
  */
 export const ng = async (template: string, options: NgOptions = {}) => {
   const { markup, styles } = await render(template, options);
 
-  return unseenStyles(styles, emitted) + markup;
+  for (const style of styles) rendered.add(style);
+
+  return markup;
 };
 
 /** A click on an element that matches `click` inside the drawing shows the state `go`. */
@@ -113,8 +127,8 @@ export const switchStates =
  */
 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<
+  const drawnStates = await Promise.all(names.map((name) => render(templates[name], options)));
+  const states = Object.fromEntries(names.map((name, index) => [name, drawnStates[index]?.markup ?? ''])) as Record<
     TState,
     string
   >;
@@ -122,12 +136,10 @@ export const ngStates = async <TState extends string>(templates: Record<TState,
 
   if (first === undefined) throw new Error('design-explore: ngStates() needs at least one state');
 
+  for (const style of drawnStates.flatMap((entry) => entry.styles)) rendered.add(style);
+
   return {
-    body:
-      unseenStyles(
-        rendered.flatMap((entry) => entry.styles),
-        emitted,
-      ) + `<div data-de-states="${first}" style="display: contents">${states[first]}</div>`,
+    body: `<div data-de-states="${first}" style="display: contents">${states[first]}</div>`,
     on: (rules: StateRule<TState>[]) => switchStates(states, rules),
   };
 };
@@ -245,27 +257,84 @@ export const placeOverlays = (root: HTMLElement) => {
   }
 };
 
+const setStyle = (
+  element: HTMLElement,
+  write: { property: 'paddingTop' | 'minHeight' | 'minWidth'; value: string },
+) => {
+  const { property, value } = write;
+
+  if (element.style[property] !== value) element.style[property] = value;
+};
+
+const fitPaddingTops = new WeakMap<HTMLElement, string>();
+
 /**
  * Grows `root` to cover every absolutely or fixed positioned element inside it, such as an open
  * overlay pane, so a frame measured or shot from `root` shows them. Skips a fixed element on all four
- * edges of the viewport, such as a backdrop. Grows sideways too with `sideways`. Safe to run again.
+ * edges of the viewport, such as a backdrop, and counts an absolute element only as far as the
+ * overflow boxes that clip it. Grows sideways and up too with `sideways`, up by a top padding that
+ * moves the content below an element drawn above it. 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 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 outOfFlowOf = () =>
+    [...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);
+
+  if (options.sideways) {
+    const fitted = fitPaddingTops.get(root);
+
+    if (fitted !== undefined) setStyle(root, { property: 'paddingTop', value: fitted });
+
+    const top = Math.min(...outOfFlowOf().map((rect) => rect.top));
+    const rootTop = root.getBoundingClientRect().top;
+
+    if (top < rootTop) {
+      const padding = parseFloat(view.getComputedStyle(root).paddingTop) || 0;
+
+      fitPaddingTops.set(root, root.style.paddingTop);
+      setStyle(root, { property: 'paddingTop', value: `${Math.ceil(2 * padding + rootTop - top)}px` });
+    } else fitPaddingTops.delete(root);
+  }
+
+  const box = root.getBoundingClientRect();
+  const style = view.getComputedStyle(root);
+  const outOfFlow = outOfFlowOf();
   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];
@@ -275,16 +344,14 @@ export const fitOutOfFlow = (root: HTMLElement, options: { sideways: boolean })
     return `${style.boxSizing === 'border-box' ? extent + after : extent - before}px`;
   };
 
-  root.style.minHeight = extentOf({
-    side: 'bottom',
-    start: box.top,
-    paddings: [style.paddingTop, style.paddingBottom],
+  setStyle(root, {
+    property: 'minHeight',
+    value: 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],
+    setStyle(root, {
+      property: 'minWidth',
+      value: extentOf({ side: 'right', start: box.left, paddings: [style.paddingLeft, style.paddingRight] }),
     });
 };
 
@@ -305,7 +372,8 @@ export type CallVariant = {
   verdict?: 'chosen' | 'rejected';
   /** The `key` of the round that drew it. Left out by a call that runs no rounds. */
   round?: string;
-  load: () => Promise<{ default: Drawing }>;
+  /** A drawing that needs `ng()` default-exports a promise of it: a top-level `await` can hang WebKit when its frame is removed. */
+  load: () => Promise<{ default: Drawing | Promise<Drawing> }>;
 };
 
 /**

package/design/define-part.ts

@@ -1,4 +1,4 @@
-import { Drawing } from './define-call';
+import { Drawing, withNgStyles } from './define-call';
 import { forceBody } from './mark-part';
 
 export { contrastRatioOf } from './contrast';
@@ -10,12 +10,16 @@ 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';
+export { withAction } from './with-action';
+export type { ActionTarget } from './with-action';
 
 /** 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';
@@ -24,6 +28,8 @@ 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.
+ * `frame` wraps the body of each of the part's own states in a demo frame (padding, a page background); a part that
+ * calls `render` of this one gets the part without 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
@@ -33,16 +39,22 @@ 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.
+ * `instant` is the reason every switch between two states happens at once; no pair then needs a 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`.
+ * `sample` makes an embedded instance of the part comparable across the states of its host, see `PartSample`.
  */
 export type Part<TProps, TState extends string = string> = {
   note: string;
   madeBy?: string[];
   states: Record<TState, TProps>;
   styles?: string;
+  frame?: (body: string, props: TProps) => string;
   widths?: number[];
   interactions?: Interaction[];
   grid?: StateGrid<TState>;
@@ -50,10 +62,30 @@ 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 }[];
+  instant?: string;
+  omits?: { option: keyof TProps & string; value: string; reason: string }[];
   rules?: PartRule<TState>[];
+  implements?: PartLink;
+  sample?: PartSample<TProps>;
   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 and, for `design compare`, the presentational `component` it renders. `design check` fails on a
+ * path that does not exist, and lists a part without a link as open.
+ */
+/**
+ * The prop `id` a host passes to name an embedded instance, and the props `marks` that carry its sample marks. Every
+ * state of one host that draws the same `id` must pass the same `marks`: `design sketch check` warns and
+ * `design sketch ready` refuses with `SAMPLE-MARK-DRIFT` otherwise. A host state that shows another sample passes
+ * another `id`.
+ */
+export type PartSample<TProps> = { id: keyof TProps & string; marks: readonly (keyof TProps & string)[] };
+
+export type PartLink = `${string}.component.ts` | { route: `/${string}`; component?: `${string}.component.ts` };
+
 /** What `play` of a motion may use, so Studio controls time: `at` schedules `fn` at `ms` into the motion on the tool's clock, `random` is seeded, `rect` measures a selector in the `from` state. */
 export type MotionContext = {
   at: (ms: number, fn: () => void) => void;
@@ -62,7 +94,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> = {
@@ -138,8 +170,10 @@ export type RenderOptions = { interaction?: Interaction };
 
 type PartSource<TProps, TState extends string, TColumn extends string> = Omit<
   Part<TProps, TState>,
-  'states' | 'grid' | 'controls' | 'motions' | 'rules' | 'render'
+  'states' | 'grid' | 'controls' | 'motions' | 'rules' | 'render' | 'frame' | 'sample'
 > & {
+  sample?: PartSample<NoInfer<TProps>>;
+  frame?: (body: string, props: NoInfer<TProps>) => string;
   motions?: Record<string, Motion<NoInfer<TState>>>;
   rules?: PartRule<NoInfer<TState>>[];
   states: Record<TState, NoInfer<TProps>>;
@@ -154,6 +188,13 @@ type PartSource<TProps, TState extends string, TColumn extends string> = Omit<
  */
 export const forceInteraction = (markup: string, interaction: Interaction) => forceBody(markup, interaction);
 
+/**
+ * The attribute that marks an element as the region `name` whose content the implementing component projects with
+ * `<ng-content>`, e.g. `<main ${slot('canvas')}>`. `design compare` empties it in the design picture, as the harness
+ * projects nothing.
+ */
+export const slot = (name: string) => `data-et-projected="${name}"`;
+
 const finished = (
   drawn: Drawing,
   { styles, interaction }: { styles?: string; interaction?: Interaction },
@@ -163,6 +204,12 @@ const finished = (
   styles: [styles, drawn.styles].filter(Boolean).join('\n'),
 });
 
+/** Draws `props` as one of the part's own states: the drawing of `render` inside the part's `frame`. */
+export const drawState = <TProps>(part: Part<TProps>, props: TProps): Promise<DrawnPart> =>
+  Promise.resolve(part.render(props)).then((drawn) =>
+    withNgStyles(part.frame ? { ...drawn, body: part.frame(drawn.body, props) } : drawn),
+  );
+
 /**
  * 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

package/design/icon-sheet.ts

@@ -31,7 +31,7 @@ const SHEET_STYLES = `
   .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-frame { position: relative; display: flex; border: 1px solid var(--surface-border, oklch(0.34 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; }

package/design/interaction-rows.ts

@@ -5,28 +5,35 @@ export type InteractionRowsOptions<TProps, TInteraction extends string> = {
 
 type RowState<TRow extends string, TInteraction extends string> = TRow | `${TRow}-${TInteraction}`;
 
+const isDisabledRow = (props: unknown) =>
+  typeof props === 'object' && props !== null && (props as { disabled?: unknown }).disabled === true;
+
 /**
  * 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.
+ * in each of `interactions` as `<row>-<interaction>`, with the props `force` returns. A row whose props carry
+ * `disabled: true` is drawn only at rest. 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 interactionsOf = (props: TProps) => (isDisabledRow(props) ? [] : interactions);
   const states = Object.fromEntries(
     entries.flatMap(([row, props]) => [
       [row, props],
-      ...interactions.map((interaction) => [`${row}-${interaction}`, force(props, interaction)]),
+      ...interactionsOf(props).map((interaction) => [`${row}-${interaction}`, force(props, interaction)]),
     ]),
   ) as Record<RowState<TRow, TInteraction>, TProps>;
   const gridRows = Object.fromEntries(
-    entries.map(([row]) => [
+    entries.map(([row, props]) => [
       row,
-      Object.fromEntries([['rest', row], ...interactions.map((interaction) => [interaction, `${row}-${interaction}`])]),
+      Object.fromEntries([
+        ['rest', row],
+        ...interactionsOf(props).map((interaction) => [interaction, `${row}-${interaction}`]),
+      ]),
     ]),
-  ) as Record<TRow, Record<'rest' | TInteraction, RowState<TRow, TInteraction>>>;
+  ) as Record<TRow, { rest: TRow } & Partial<Record<TInteraction, RowState<TRow, TInteraction>>>>;
 
   return { states, grid: { columns: ['rest', ...interactions] as const, rows: gridRows } };
 };

package/design/logo-sheet.ts

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

package/design/mark-part.ts

@@ -37,11 +37,19 @@ export const markBody = (body: string, key: string) => {
   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. */
+const DISABLED_ATTRIBUTE = /\s(?:disabled(?=[\s=/>]|$)|aria-disabled\s*=\s*["']?true\b)/i;
+
+const isDisabledMarkup = (attributes: string) => DISABLED_ATTRIBUTE.test(attributes);
+
+/**
+ * Forces `interaction` on the first element of `body` the way a frame forces it on the root of a part. A disabled
+ * element stays at rest: it gets no forced hover, active or focus-visible.
+ */
 export const forceBody = (body: string, interaction: Interaction) => {
   const attributesAt = attributesAtOf(body);
 
   if (attributesAt === null) return body;
+  if (interaction !== 'disabled' && isDisabledMarkup(ATTRIBUTES.exec(body.slice(attributesAt))?.[0] ?? '')) return body;
 
   const forced = interaction === 'disabled' ? ' disabled aria-disabled="true"' : ` data-et-force="${interaction}"`;
 
@@ -117,6 +125,23 @@ const slotProps = (value: unknown, { key, depth = 0 }: { key: string; depth?: nu
   return value;
 };
 
+const SAMPLES = Symbol.for('@ethlete/cli/design/samples');
+
+/** Reports `props` to the sample recorder a check installs, when the part declares a `sample` and the props carry its `id`. */
+const recordSample = ({ key, part }: { key: string; part: unknown }, props: unknown) => {
+  const record = (globalThis as Record<symbol, unknown>)[SAMPLES];
+  const sample = isPlainObject(part) ? part['sample'] : undefined;
+
+  if (typeof record !== 'function' || !isPlainObject(sample) || !isPlainObject(props)) return;
+
+  const id = props[String(sample['id'])];
+  const marks = Array.isArray(sample['marks']) ? (sample['marks'] as unknown[]).map(String) : [];
+
+  if (typeof id !== 'string' || id === '') return;
+
+  record({ part: key, id, marks: Object.fromEntries(marks.map((mark) => [mark, props[mark] ?? null])) });
+};
+
 const markDrawing = <TDrawing extends Drawing>(drawn: TDrawing, key: string): TDrawing =>
   typeof drawn?.body === 'string' ? { ...drawn, body: markBody(drawn.body, key) } : drawn;
 
@@ -135,9 +160,34 @@ export const markPart = <TProps, TState extends string>(
   return {
     ...part,
     render: (props: TProps, options?: RenderOptions) => {
+      recordSample({ key, part }, props);
+
       const drawn = render.call(part, slotProps(props, { key }) as TProps, options);
 
       return drawn instanceof Promise ? drawn.then((done) => markDrawing(done, key)) : markDrawing(drawn, key);
     },
   };
 };
+
+const markOutput = (output: unknown, key: string) =>
+  typeof output === 'string' ? markBody(output, key) : markDrawing(output as Drawing, key);
+
+/**
+ * `value` as a named export of the part `key`: a function whose markup, or drawing body, comes back with its first
+ * element marked as the root of `key`, and the markup of its arguments as slotted into `key`. Any other value, a
+ * class included, stays as it is. A call whose first argument carries the `sample` id of `part` is reported as a sample.
+ */
+export const markNamed = <T>(value: T, { key, part }: { key: string; part?: unknown }): T => {
+  if (typeof value !== 'function' || /^class\b/u.test(Function.prototype.toString.call(value))) return value;
+
+  return function (this: unknown, ...args: unknown[]) {
+    recordSample({ key, part }, args[0]);
+
+    const output = value.apply(
+      this,
+      args.map((arg) => slotProps(arg, { key })),
+    );
+
+    return output instanceof Promise ? output.then((done) => markOutput(done, key)) : markOutput(output, key);
+  } as T;
+};