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

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';
@@ -18,6 +18,8 @@ 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';
@@ -26,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
@@ -36,18 +40,21 @@ export type Interaction = 'hover' | 'focus-visible' | 'active' | 'disabled';
  * 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>;
@@ -56,17 +63,28 @@ export type Part<TProps, TState extends string = string> = {
   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. `design check` fails on a path that does not exist, and lists a part without a link as open.
+ * 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.
  */
-export type PartLink = `${string}.component.ts` | { route: `/${string}` };
+/**
+ * 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 = {
@@ -152,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>>;
@@ -168,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 },
@@ -177,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/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;
+};

package/design/token-sheet.ts

@@ -18,7 +18,7 @@ const SHEET_STYLES = `
   .ts-root { position: relative; display: flex; flex-direction: column; gap: var(--space-4, 1.6rem); width: 960px; padding: var(--space-6, 2.4rem); box-sizing: border-box; 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); }
   .ts-title { margin: 0; font-size: var(--text-xl, 1.7rem); line-height: var(--text-xl-line, 2.2rem); font-weight: var(--weight-strong, 600); }
   .ts-note { margin: 0; max-width: 64rem; color: var(--text-muted, oklch(0.72 0 0)); }
-  .ts-panel { margin: 0; padding: var(--space-4, 1.6rem); background: var(--surface, oklch(0.17 0 0)); border: 1px solid var(--surface-border, oklch(0.34 0 0)); border-radius: var(--radius-control-lg, 1rem); }
+  .ts-panel { margin: 0; padding: var(--space-4, 1.6rem); border: 1px solid var(--surface-border, oklch(0.34 0 0)); border-radius: var(--radius-control-lg, 1rem); }
   .ts-list { list-style: none; display: flex; flex-direction: column; gap: var(--space-1, 0.4rem); }
   .ts-row { display: grid; grid-template-columns: 200px 240px 1fr; align-items: center; gap: var(--space-3, 1.2rem); min-height: var(--row, 2.4rem); }
   .ts-name { font-family: var(--font-code, ui-monospace, "SF Mono", Menlo, Consolas, monospace); font-size: var(--text-sm, 1.15rem); line-height: var(--text-sm-line, 1.6rem); color: var(--text-muted, oklch(0.72 0 0)); }

package/design/web/frame-fit.ts

@@ -0,0 +1,7 @@
+/** Sizes the frame root to its content; `padded` keeps a 16 px margin around it, which a bare compare shot leaves out. */
+export const fitRoot = (root: HTMLElement, options: { padded: boolean }) => {
+  root.ownerDocument.documentElement.style.overflow = 'hidden';
+  root.style.width = 'max-content';
+
+  if (options.padded) root.style.padding = '16px';
+};

package/design/web/frame-surfaces.ts

@@ -0,0 +1,294 @@
+export type FrameSurfaceTheme = {
+  name: string;
+  type: string;
+  elevation: number;
+  isDefault: boolean;
+  colorThemeVariants: Partial<Record<string, string>>;
+};
+export type FrameColorTheme = { name: string; type: string | null; isDefault: boolean };
+export type FrameThemes = { surfaces: FrameSurfaceTheme[]; colors: FrameColorTheme[] };
+
+export const AUTO_SURFACE_ATTRIBUTE = 'data-et-auto-surface';
+export const SURFACE_INTERACTIVE_ATTRIBUTE = 'data-et-surface-interactive';
+export const SEMANTIC_COLOR_ATTRIBUTE = 'data-et-semantic-color';
+
+const SURFACE_CLASS_PREFIX = 'et-surface--';
+const COLOR_CLASS_PREFIX = 'et-color--';
+const SURFACE_INTERACTIVE_CLASS = 'et-surface-interactive';
+const SURFACE_CLASS_SELECTOR = /^\.et-surface--([\w-]+)$/u;
+const COLOR_CLASS_SELECTOR = /^\.et-color--([\w-]+)$/u;
+const RESERVED_COLORS = new Set(['default', 'surface']);
+
+const surfaceVarsOf = (style: CSSStyleDeclaration) => {
+  const type = style.getPropertyValue('--et-surface-type').trim();
+  const elevation = Number.parseInt(style.getPropertyValue('--et-surface-elevation'), 10);
+
+  return type && Number.isFinite(elevation) ? { type, elevation } : null;
+};
+
+const colorThemeVariantsOf = (style: CSSStyleDeclaration) =>
+  Object.fromEntries(
+    style
+      .getPropertyValue('--et-surface-color-theme-variants')
+      .split(',')
+      .map((entry) => entry.trim().split(/\s+/u))
+      .filter((pair): pair is [string, string] => pair.length === 2),
+  );
+
+const scopeNamesOf = (rule: CSSStyleRule, selector: RegExp) =>
+  rule.selectorText
+    .split(',')
+    .map((part) => selector.exec(part.trim())?.[1])
+    .filter((name): name is string => name !== undefined);
+
+const themesOfRules = (rules: CSSRuleList, themes: FrameThemes) => {
+  for (const rule of Array.from(rules)) {
+    if (rule instanceof CSSStyleRule) {
+      const surface = surfaceVarsOf(rule.style);
+
+      if (surface) {
+        const names = scopeNamesOf(rule, SURFACE_CLASS_SELECTOR);
+        const isDefault = names.includes(`default-${surface.type}`);
+        const registered = names.length > 1 ? names.filter((name) => name !== `default-${surface.type}`) : names;
+        const colorThemeVariants = colorThemeVariantsOf(rule.style);
+
+        registered.forEach((name) => themes.surfaces.push({ name, ...surface, isDefault, colorThemeVariants }));
+      }
+
+      if (rule.style.getPropertyValue('--et-color-primary')) {
+        const names = scopeNamesOf(rule, COLOR_CLASS_SELECTOR);
+        const type = rule.style.getPropertyValue('--et-color-theme-type').trim() || null;
+        const isDefault = names.includes('default');
+
+        names
+          .filter((name) => !RESERVED_COLORS.has(name))
+          .forEach((name) => themes.colors.push({ name, type, isDefault }));
+      }
+    }
+
+    if ('cssRules' in rule) themesOfRules((rule as CSSGroupingRule).cssRules, themes);
+  }
+
+  return themes;
+};
+
+const sheetThemes = new WeakMap<CSSStyleSheet, FrameThemes>();
+
+/**
+ * The surface and colour themes the frame's stylesheets register, as the SDK's generated theme CSS writes them: every
+ * `.et-surface--<name>` rule that sets `--et-surface-type` and `--et-surface-elevation` (with its
+ * `--et-surface-color-theme-variants`), and every `.et-color--<name>` rule that sets `--et-color-primary` (with its
+ * `--et-color-theme-type`).
+ */
+export const registeredThemesOf = (document: Document): FrameThemes => {
+  const all: FrameThemes = { surfaces: [], colors: [] };
+
+  for (const sheet of Array.from(document.styleSheets)) {
+    let themes = sheetThemes.get(sheet);
+
+    if (!themes) {
+      try {
+        themes = themesOfRules(sheet.cssRules, { surfaces: [], colors: [] });
+      } catch {
+        // A cross-origin sheet hides its rules.
+        continue;
+      }
+
+      sheetThemes.set(sheet, themes);
+    }
+
+    all.surfaces.push(...themes.surfaces);
+    all.colors.push(...themes.colors);
+  }
+
+  return all;
+};
+
+const surfaceThemeOf = (element: Element, themes: FrameSurfaceTheme[]): FrameSurfaceTheme | null => {
+  for (let current: Element | null = element; current; current = current.parentElement) {
+    for (const className of Array.from(current.classList)) {
+      if (!className.startsWith(SURFACE_CLASS_PREFIX)) continue;
+
+      const name = className.slice(SURFACE_CLASS_PREFIX.length);
+      const theme = themes.find((candidate) =>
+        name.startsWith('default-')
+          ? candidate.isDefault && `default-${candidate.type}` === name
+          : candidate.name === name,
+      );
+
+      if (theme) return theme;
+    }
+  }
+
+  const vars = surfaceVarsOf(getComputedStyle(element));
+  const matches = vars ? themes.filter((theme) => theme.type === vars.type && theme.elevation === vars.elevation) : [];
+
+  return matches.find((theme) => theme.isDefault) ?? matches[0] ?? null;
+};
+
+const colorVariantOf = (
+  surface: FrameSurfaceTheme | null,
+  { chosen, colors }: { chosen: string; colors: FrameColorTheme[] },
+) => {
+  const variant = surface?.colorThemeVariants[chosen];
+
+  return variant && colors.some((theme) => theme.name === variant) ? variant : chosen;
+};
+
+const appliedSurface = new WeakMap<Element, string>();
+const appliedColor = new WeakMap<Element, { chosen: string; variant: string }>();
+
+const defaultColorOf = (colors: FrameColorTheme[]) => colors.find((theme) => theme.isDefault)?.name ?? null;
+
+const chosenColorOf = (element: Element | null, colors: FrameColorTheme[]) => {
+  for (let current = element; current; current = current.parentElement) {
+    const applied = appliedColor.get(current);
+
+    if (applied) return applied.chosen;
+
+    for (const className of Array.from(current.classList)) {
+      if (!className.startsWith(COLOR_CLASS_PREFIX)) continue;
+
+      const name = className.slice(COLOR_CLASS_PREFIX.length);
+
+      if (name === 'default') return defaultColorOf(colors);
+      if (colors.some((theme) => theme.name === name)) return name;
+    }
+  }
+
+  return defaultColorOf(colors);
+};
+
+const applyColor = (element: Element, color: { chosen: string; variant: string } | null) => {
+  const previous = appliedColor.get(element);
+
+  if (previous && previous.variant !== color?.variant)
+    element.classList.remove(`${COLOR_CLASS_PREFIX}${previous.variant}`);
+
+  if (!color) {
+    appliedColor.delete(element);
+
+    return;
+  }
+
+  appliedColor.set(element, color);
+  if (!element.classList.contains(`${COLOR_CLASS_PREFIX}${color.variant}`))
+    element.classList.add(`${COLOR_CLASS_PREFIX}${color.variant}`);
+};
+
+const resolveAutoSurface = (element: Element, themes: FrameSurfaceTheme[]) => {
+  const parent = element.parentElement ? surfaceVarsOf(getComputedStyle(element.parentElement)) : null;
+  const name = parent
+    ? (themes.find((theme) => theme.type === parent.type && theme.elevation === parent.elevation + 1)?.name ?? null)
+    : null;
+  const previous = appliedSurface.get(element);
+
+  if (previous !== undefined && previous !== name) element.classList.remove(`${SURFACE_CLASS_PREFIX}${previous}`);
+
+  if (name === null) {
+    appliedSurface.delete(element);
+
+    return;
+  }
+
+  appliedSurface.set(element, name);
+  if (!element.classList.contains(`${SURFACE_CLASS_PREFIX}${name}`))
+    element.classList.add(`${SURFACE_CLASS_PREFIX}${name}`);
+};
+
+const resolveColor = (element: Element, themes: FrameThemes) => {
+  const type = element.getAttribute(SEMANTIC_COLOR_ATTRIBUTE);
+
+  if (type) {
+    const chosen = themes.colors.find((theme) => theme.type === type)?.name;
+
+    applyColor(
+      element,
+      chosen
+        ? {
+            chosen,
+            variant: colorVariantOf(surfaceThemeOf(element, themes.surfaces), { chosen, colors: themes.colors }),
+          }
+        : null,
+    );
+
+    return;
+  }
+
+  const chosen = element.hasAttribute(AUTO_SURFACE_ATTRIBUTE)
+    ? chosenColorOf(element.parentElement, themes.colors)
+    : null;
+
+  if (!chosen || !element.parentElement) {
+    applyColor(element, null);
+
+    return;
+  }
+
+  const variant = colorVariantOf(surfaceThemeOf(element, themes.surfaces), { chosen, colors: themes.colors });
+  const inherited = colorVariantOf(surfaceThemeOf(element.parentElement, themes.surfaces), {
+    chosen,
+    colors: themes.colors,
+  });
+
+  applyColor(element, variant === inherited ? null : { chosen, variant });
+};
+
+/**
+ * Resolves the theming attributes under `root` in document order, outer first: `[data-et-auto-surface]` gets the
+ * `et-surface--<name>` class of the theme one elevation above the surface it sits on, with the same type, like
+ * `etAutoSurface` (without such a theme it keeps the parent surface), plus the class of that surface's
+ * `colorThemeVariants` swap of the inherited accent, like `etProvideSurface`. `[data-et-semantic-color="<type>"]`
+ * gets the `et-color--<name>` class of the first colour theme of that type, swapped for its surface, like
+ * `injectSemanticColorTheme`; without a theme of that type it gets none.
+ */
+export const resolveTheming = (root: ParentNode, themes: FrameThemes) => {
+  for (const element of Array.from(
+    root.querySelectorAll(`[${AUTO_SURFACE_ATTRIBUTE}], [${SEMANTIC_COLOR_ATTRIBUTE}]`),
+  )) {
+    if (element.hasAttribute(AUTO_SURFACE_ATTRIBUTE)) resolveAutoSurface(element, themes.surfaces);
+
+    resolveColor(element, themes);
+  }
+};
+
+/**
+ * Resolves the theming attributes under `root` now and again after every change of its markup or of the page's
+ * stylesheets: auto surfaces and semantic colours as `resolveTheming`, and `[data-et-surface-interactive]` as `etSurfaceInteractive`, whose CSS
+ * (`interactiveCss`) goes into the page once. Returns the resolve function.
+ */
+export const watchSurfaces = (root: HTMLElement, interactiveCss: string) => {
+  const document = root.ownerDocument;
+  let styled = false;
+
+  const resolve = () => {
+    const interactive = Array.from(root.querySelectorAll(`[${SURFACE_INTERACTIVE_ATTRIBUTE}]`));
+
+    interactive.forEach((element) => {
+      if (!element.classList.contains(SURFACE_INTERACTIVE_CLASS)) element.classList.add(SURFACE_INTERACTIVE_CLASS);
+    });
+
+    if (interactive.length > 0 && !styled) {
+      const style = document.createElement('style');
+
+      styled = true;
+      style.textContent = interactiveCss;
+      document.head.append(style);
+    }
+
+    if (root.querySelector(`[${AUTO_SURFACE_ATTRIBUTE}], [${SEMANTIC_COLOR_ATTRIBUTE}]`))
+      resolveTheming(root, registeredThemesOf(document));
+  };
+
+  resolve();
+
+  new MutationObserver(resolve).observe(root, {
+    childList: true,
+    subtree: true,
+    attributes: true,
+    attributeFilter: ['class', AUTO_SURFACE_ATTRIBUTE, SURFACE_INTERACTIVE_ATTRIBUTE, SEMANTIC_COLOR_ATTRIBUTE],
+  });
+  new MutationObserver(resolve).observe(document.head, { childList: true, subtree: true, characterData: true });
+
+  return resolve;
+};