@tai42/studio-sdk 25.0.0 → 26.0.0

package/dist/token-rules.js

@@ -0,0 +1,64 @@
+/**
+ * Source rules over the design-token names, shared by the repo's token-usage gate and
+ * by any host that scans its own sources with the same rule (exported from
+ * `@tai42/studio-sdk/testing`). Each rule reads one source text and returns its
+ * offences; which files to read is the caller's choice, the rule never varies.
+ */
+/**
+ * The property a declaration's value belongs to: the last `name:` before the
+ * value, with no statement boundary in between. Written as a backwards search
+ * rather than a forward `property: value` match so that a value containing its
+ * own commas and parentheses — `linear-gradient(90deg, …)`, or the next entry of
+ * a JSX style object — cannot make the scan attribute the value to the wrong
+ * property or miss it entirely.
+ */
+export function governingProperty(source, valueIndex) {
+    const match = /([-A-Za-z][\w-]*)\s*:\s*[^;{}:]*$/.exec(source.slice(0, valueIndex));
+    return match?.[1];
+}
+/** Every reference to a destructive role token, in a stylesheet or a JSX inline style. */
+const DESTRUCTIVE_REFERENCE = /var\(\s*--tai-color-(?:on-)?destructive/g;
+/** The one rule whose label sits on the destructive fill. */
+const DESTRUCTIVE_BUTTON_SELECTOR = /^\.tai-btn-danger(?![\w-])/;
+/**
+ * Whether the declaration at `valueIndex` sits inside a CSS rule whose every
+ * selector is the destructive button. The selector is the text between the
+ * previous statement boundary and the innermost open brace, with comments removed.
+ */
+function insideDestructiveButtonRule(source, valueIndex) {
+    const before = source.slice(0, valueIndex);
+    const open = before.lastIndexOf('{');
+    if (open === -1 || before.lastIndexOf('}') > open)
+        return false;
+    const head = before.slice(0, open);
+    const start = Math.max(head.lastIndexOf('}'), head.lastIndexOf('{'), head.lastIndexOf(';')) + 1;
+    const selectors = head
+        .slice(start)
+        .replace(/\/\*[\s\S]*?\*\//g, '')
+        .split(',')
+        .map((selector) => selector.trim());
+    return selectors.every((selector) => DESTRUCTIVE_BUTTON_SELECTOR.test(selector));
+}
+/**
+ * The properties in `source` that paint text with a destructive role token, in the
+ * order they appear. The destructive tokens are the fill, its hover and the label on
+ * that fill: a fill colour as text fails contrast on the dark grounds, so error text
+ * takes `--tai-color-err-text` instead. A `color` declaration (CSS or JSX) is an
+ * offence anywhere but the `.tai-btn-danger` rule, where the label colour belongs. A
+ * reference whose property cannot be read is reported as `<no property found>`: an
+ * unattributable declaration is a hole in the rule, not a pass.
+ */
+export function destructiveColorOffences(source) {
+    const offences = [];
+    for (const match of source.matchAll(DESTRUCTIVE_REFERENCE)) {
+        const property = governingProperty(source, match.index);
+        if (property === undefined) {
+            offences.push('<no property found>');
+        }
+        else if (property === 'color' && !insideDestructiveButtonRule(source, match.index)) {
+            offences.push(property);
+        }
+    }
+    return offences;
+}
+//# sourceMappingURL=token-rules.js.map

package/dist/token-rules.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-rules.js","sourceRoot":"","sources":["../src/token-rules.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;;;GAOG;AACH,MAAM,UAAU,iBAAiB,CAAC,MAAc,EAAE,UAAkB;IAClE,MAAM,KAAK,GAAG,mCAAmC,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC,CAAC;IACpF,OAAO,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC;AACpB,CAAC;AAED,0FAA0F;AAC1F,MAAM,qBAAqB,GAAG,0CAA0C,CAAC;AAEzE,6DAA6D;AAC7D,MAAM,2BAA2B,GAAG,4BAA4B,CAAC;AAEjE;;;;GAIG;AACH,SAAS,2BAA2B,CAAC,MAAc,EAAE,UAAkB;IACrE,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC;IAC3C,MAAM,IAAI,GAAG,MAAM,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IACrC,IAAI,IAAI,KAAK,CAAC,CAAC,IAAI,MAAM,CAAC,WAAW,CAAC,GAAG,CAAC,GAAG,IAAI;QAAE,OAAO,KAAK,CAAC;IAChE,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;IACnC,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,EAAE,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,EAAE,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC;IAChG,MAAM,SAAS,GAAG,IAAI;SACnB,KAAK,CAAC,KAAK,CAAC;SACZ,OAAO,CAAC,mBAAmB,EAAE,EAAE,CAAC;SAChC,KAAK,CAAC,GAAG,CAAC;SACV,GAAG,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;IACtC,OAAO,SAAS,CAAC,KAAK,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,2BAA2B,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC;AACnF,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,wBAAwB,CAAC,MAAc;IACrD,MAAM,QAAQ,GAAa,EAAE,CAAC;IAC9B,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,QAAQ,CAAC,qBAAqB,CAAC,EAAE,CAAC;QAC3D,MAAM,QAAQ,GAAG,iBAAiB,CAAC,MAAM,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC;QACxD,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;YAC3B,QAAQ,CAAC,IAAI,CAAC,qBAAqB,CAAC,CAAC;QACvC,CAAC;aAAM,IAAI,QAAQ,KAAK,OAAO,IAAI,CAAC,2BAA2B,CAAC,MAAM,EAAE,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC;YACrF,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QAC1B,CAAC;IACH,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tai42/studio-sdk",
-  "version": "25.0.0",
+  "version": "26.0.0",
   "description": "The Studio plugin contract, shared UI components, and hooks that every feature builds on.",
   "license": "Apache-2.0",
   "author": "tai42 <oss@tai42.ai>",
@@ -80,23 +80,23 @@
     "@types/node": "^22.10.5",
     "@types/react": "^19.3.0",
     "@types/react-dom": "^19.3.0",
-    "@vitejs/plugin-react": "^4.7.0",
+    "@vitejs/plugin-react": "^5.2.0",
     "@vitest/coverage-v8": "^5.0.4",
     "jsdom": "^30.0.1",
-    "react": "^19.3.0",
-    "react-dom": "^19.3.0",
-    "vitest": "^5.0.4"
+    "react": "^19.3.1",
+    "react-dom": "^19.3.1",
+    "vitest": "^5.0.5"
   },
   "dependencies": {
     "@fontsource-variable/geist-mono": "^5.2.7",
     "@fontsource-variable/inter": "^5.2.8",
-    "@radix-ui/react-checkbox": "^1.3.12",
+    "@radix-ui/react-checkbox": "^1.4.1",
     "@radix-ui/react-dialog": "^1.2.0",
     "@radix-ui/react-radio-group": "^1.4.8",
     "@radix-ui/react-select": "^2.3.8",
     "@radix-ui/react-tabs": "^1.1.22",
     "@radix-ui/react-tooltip": "^1.3.0",
-    "@tai42/api-client": "25.0.0"
+    "@tai42/api-client": "26.0.0"
   },
   "scripts": {
     "build": "tsc -b tsconfig.build.json && node scripts/copy-assets.mjs",

package/src/components/action-menu.tsx

@@ -0,0 +1,160 @@
+/**
+ * `ActionMenu` — a row's or a card's overflow menu: a ghost "Actions" button
+ * whose accessible name the caller completes ("Actions for <name>", which keeps
+ * the visible word at its start) that opens a `role="menu"` list of
+ * `role="menuitem"` buttons, the WAI-ARIA menu-button pattern.
+ *
+ * Opening moves focus to the first item; ArrowDown/ArrowUp move between items
+ * (wrapping), Home/End jump to the ends, Escape closes and returns focus to the
+ * trigger, Tab closes. Activating an item closes the menu, returns focus to the
+ * trigger, then runs the item's action, so a dialog the action opens takes focus
+ * from a settled trigger. A pointer press outside the menu closes it.
+ *
+ * The caller passes only the items the session may use; with none the menu is
+ * not drawn at all (a hidden control takes no line).
+ */
+import { type KeyboardEvent, type ReactNode, useEffect, useId, useRef, useState } from 'react';
+
+import { ChevronDownIcon } from './icons';
+
+export interface ActionMenuItem {
+  readonly id: string;
+  readonly label: string;
+  readonly onSelect: () => void;
+  /** Paints the item in the error tone (a destructive action). */
+  readonly danger?: boolean;
+}
+
+export interface ActionMenuProps {
+  /** The trigger's accessible name, e.g. "Actions for Acme". */
+  readonly label: string;
+  readonly items: readonly ActionMenuItem[];
+}
+
+export function ActionMenu({ label, items }: ActionMenuProps): ReactNode {
+  const [open, setOpen] = useState(false);
+  const menuId = useId();
+  const triggerRef = useRef<HTMLButtonElement>(null);
+  const menuRef = useRef<HTMLDivElement>(null);
+  const itemRefs = useRef<(HTMLButtonElement | null)[]>([]);
+
+  useEffect(() => {
+    if (!open) return undefined;
+    itemRefs.current[0]?.focus();
+    const onPointerDown = (event: PointerEvent): void => {
+      const target = event.target as Node | null;
+      if (target === null) return;
+      if (menuRef.current?.contains(target) === true) return;
+      if (triggerRef.current?.contains(target) === true) return;
+      setOpen(false);
+    };
+    document.addEventListener('pointerdown', onPointerDown);
+    return () => {
+      document.removeEventListener('pointerdown', onPointerDown);
+    };
+  }, [open]);
+
+  if (items.length === 0) return null;
+
+  const close = (): void => {
+    setOpen(false);
+    triggerRef.current?.focus();
+  };
+
+  const focusItem = (index: number): void => {
+    const count = items.length;
+    itemRefs.current[((index % count) + count) % count]?.focus();
+  };
+
+  const onMenuKeyDown = (event: KeyboardEvent<HTMLDivElement>): void => {
+    const current = itemRefs.current.findIndex((item) => item === document.activeElement);
+    switch (event.key) {
+      case 'ArrowDown':
+        event.preventDefault();
+        focusItem(current + 1);
+        break;
+      case 'ArrowUp':
+        event.preventDefault();
+        focusItem(current - 1);
+        break;
+      case 'Home':
+        event.preventDefault();
+        focusItem(0);
+        break;
+      case 'End':
+        event.preventDefault();
+        focusItem(items.length - 1);
+        break;
+      case 'Escape':
+        event.preventDefault();
+        event.stopPropagation();
+        close();
+        break;
+      case 'Tab':
+        setOpen(false);
+        break;
+      default:
+        break;
+    }
+  };
+
+  return (
+    <div className="tai-action-menu">
+      <button
+        ref={triggerRef}
+        type="button"
+        className="tai-btn tai-btn-ghost"
+        aria-label={label}
+        aria-haspopup="menu"
+        aria-expanded={open}
+        aria-controls={open ? menuId : undefined}
+        onClick={() => {
+          setOpen((was) => !was);
+        }}
+        onKeyDown={(event) => {
+          if (event.key === 'ArrowDown' && !open) {
+            event.preventDefault();
+            setOpen(true);
+          }
+        }}
+      >
+        Actions
+        <ChevronDownIcon />
+      </button>
+      {open ? (
+        <div
+          ref={menuRef}
+          id={menuId}
+          role="menu"
+          tabIndex={-1}
+          aria-label={label}
+          className="tai-action-menu-list"
+          onKeyDown={onMenuKeyDown}
+        >
+          {items.map((item, index) => (
+            <button
+              key={item.id}
+              ref={(node) => {
+                itemRefs.current[index] = node;
+              }}
+              type="button"
+              role="menuitem"
+              tabIndex={-1}
+              className={
+                item.danger === true
+                  ? 'tai-action-menu-item tai-action-menu-item-danger'
+                  : 'tai-action-menu-item'
+              }
+              onClick={() => {
+                close();
+                item.onSelect();
+              }}
+            >
+              {item.label}
+            </button>
+          ))}
+        </div>
+      ) : null}
+    </div>
+  );
+}

package/src/components/agent-picker.tsx

@@ -0,0 +1,53 @@
+/**
+ * `AgentPicker` — picks a registered agent by name from the agent list read
+ * (`GET /api/agents`) the host owns and hands in. Presentational: it fetches nothing
+ * and names no query library. It draws the read's states and its own copy, and flags
+ * a stored agent the loaded list does not hold as "not registered".
+ */
+import type { AgentListing } from '@tai42/api-client';
+import type { ReactNode } from 'react';
+
+import { AppLink } from '../navigation/app-link';
+import { type ListReadFlags, type NamedListCopy, NamedListPicker } from './named-list-picker';
+
+/** The subset of the agent list read this picker reads; a TanStack query result satisfies it. */
+export interface AgentListQuery extends ListReadFlags {
+  readonly data: AgentListing | undefined;
+}
+
+export interface AgentPickerProps {
+  readonly query: AgentListQuery;
+  readonly value: string;
+  readonly onValueChange: (value: string) => void;
+  /** The host form's field error, shown under the control while a `Select` renders. */
+  readonly error?: string | undefined;
+}
+
+const COPY: NamedListCopy = {
+  label: 'Agent',
+  loadingPlaceholder: 'Loading agents…',
+  placeholder: 'Select an agent',
+  forbiddenNote:
+    'This session cannot list agents. Picking one needs read access to GET /api/agents; ask an administrator to grant it.',
+  emptyNote: 'No agents are registered on this deployment.',
+  emptyAction: (
+    <AppLink to="agents" className="tai-link">
+      Open the Agents screen
+    </AppLink>
+  ),
+  unlistedLabel: 'not registered',
+};
+
+export function AgentPicker({ query, value, onValueChange, error }: AgentPickerProps): ReactNode {
+  const names = (query.data?.items ?? []).map((item) => item.name);
+  return (
+    <NamedListPicker
+      query={query}
+      names={names}
+      value={value}
+      onValueChange={onValueChange}
+      error={error}
+      copy={COPY}
+    />
+  );
+}

package/src/components/channel-picker.tsx

@@ -0,0 +1,68 @@
+/**
+ * `ChannelPicker` — picks an installed channel plugin by name from the channel list
+ * read (`GET /api/channels`) the host owns and hands in. Presentational: it fetches
+ * nothing and names no query library. It draws the read's states and its own copy,
+ * and flags a stored channel the loaded list does not hold as "not installed".
+ */
+import type { Channels } from '@tai42/api-client';
+import type { ReactNode } from 'react';
+
+import { AppLink } from '../navigation/app-link';
+import { type ListReadFlags, type NamedListCopy, NamedListPicker } from './named-list-picker';
+
+/** The subset of the channel list read this picker reads; a TanStack query result satisfies it. */
+export interface ChannelListQuery extends ListReadFlags {
+  readonly data: Channels | undefined;
+}
+
+export interface ChannelPickerProps {
+  readonly query: ChannelListQuery;
+  readonly value: string;
+  readonly onValueChange: (value: string) => void;
+  /** The host form's field error, shown under the control while a `Select` renders. */
+  readonly error?: string | undefined;
+}
+
+/**
+ * The named channel's declared hint for a route's identity: the hint, `null` for a
+ * listed channel that declares none, `undefined` when the name is not listed.
+ */
+export function channelIdentityHint(data: Channels, name: string): string | null | undefined {
+  const entry = data.channels.find((channel) => channel.name === name);
+  return entry === undefined ? undefined : entry.identity_hint;
+}
+
+const COPY: NamedListCopy = {
+  label: 'Channel',
+  description: 'An installed channel plugin; the answer goes back on the same channel.',
+  loadingPlaceholder: 'Loading channels…',
+  placeholder: 'Select a channel',
+  forbiddenNote:
+    'This session cannot list channels. Picking one needs read access to GET /api/channels; ask an administrator to grant it.',
+  emptyNote: 'No channels are installed on this deployment.',
+  emptyAction: (
+    <AppLink to="marketplace" search={{ kind: 'channel' }} className="tai-link">
+      Browse channel plugins
+    </AppLink>
+  ),
+  unlistedLabel: 'not installed',
+};
+
+export function ChannelPicker({
+  query,
+  value,
+  onValueChange,
+  error,
+}: ChannelPickerProps): ReactNode {
+  const names = (query.data?.channels ?? []).map((channel) => channel.name);
+  return (
+    <NamedListPicker
+      query={query}
+      names={names}
+      value={value}
+      onValueChange={onValueChange}
+      error={error}
+      copy={COPY}
+    />
+  );
+}

package/src/components/components.css

@@ -167,6 +167,8 @@
   /* Radix hard-codes `tabIndex: 0` on every `TabsContent`, so a tab panel is a
      tab stop whether or not it holds one — it needs the ring like any other. */
   .tai-tabpanel:focus-visible,
+  .tai-stepper-button:focus-visible,
+  .tai-action-menu-item:focus-visible,
   .tai-dialog:focus-visible {
     outline: 2px solid var(--tai-color-focus-ring);
     outline-offset: 2px;
@@ -279,14 +281,14 @@
   }
 
   .tai-btn-danger {
-    background: var(--tai-color-danger);
-    border-color: var(--tai-color-danger);
-    color: var(--tai-color-danger-text);
+    background: var(--tai-color-destructive);
+    border-color: var(--tai-color-destructive);
+    color: var(--tai-color-on-destructive);
   }
 
   .tai-btn-danger:hover:not(:disabled):not([aria-disabled='true']) {
-    background: var(--tai-color-danger-hover);
-    border-color: var(--tai-color-danger-hover);
+    background: var(--tai-color-destructive-hover);
+    border-color: var(--tai-color-destructive-hover);
   }
 
   /* A square button whose only content is a 16 px icon; its accessible name
@@ -331,6 +333,34 @@
     color: var(--tai-color-accent-hover);
   }
 
+  /* -- Holder list ----------------------------------------------------------
+     The things that still use a name, each a link to where it lives. A long
+     list scrolls inside its own bordered region, which takes focus so the
+     keyboard can scroll it. */
+  .tai-holder-list {
+    padding: var(--tai-space-2) var(--tai-space-3);
+    max-height: 16rem;
+    overflow-y: auto;
+    color: var(--tai-color-text);
+    border: 1px solid var(--tai-color-border);
+    border-radius: var(--tai-radius-sm);
+  }
+
+  .tai-holder-list > ul {
+    margin: 0;
+    padding: 0;
+    list-style: none;
+  }
+
+  .tai-holder-list > ul > li + li {
+    margin-top: var(--tai-space-1);
+  }
+
+  .tai-holder-lead {
+    margin: 0 0 var(--tai-space-2);
+    color: var(--tai-color-err-text);
+  }
+
   /* -- Icons ----------------------------------------------------------------
      Rendered at 16 px in currentColor at full opacity; a 24-unit viewBox and a
      1.6 stroke keep the whole set optically consistent. */
@@ -362,7 +392,9 @@
   .tai-nav-link > svg,
   .tai-segment > svg,
   .tai-select-trigger > svg,
-  .tai-status > svg {
+  .tai-status > svg,
+  .tai-stepper-button > svg,
+  .tai-action-menu-item > svg {
     flex: none;
   }
 
@@ -1236,12 +1268,14 @@
   .tai-table .tai-choice,
   .tai-table .tai-nav-item,
   .tai-table .tai-nav-link,
-  .tai-table .tai-select-trigger {
+  .tai-table .tai-select-trigger,
+  .tai-table .tai-stepper-button,
+  .tai-table .tai-action-menu-item {
     min-width: auto;
     overflow-wrap: normal;
   }
 
-  /* `.tai-segment` takes the wrap half ONLY. The eight above carry
+  /* `.tai-segment` takes the wrap half ONLY. The ten above carry
      `min-width: 0`, so `auto` is what hands them an intrinsic minimum back;
      this one carries a 28 px / 44 px POINTER TARGET (WCAG 2.5.8), and `auto` on
      a flex item is the CONTENT-based minimum — for the icon-only option this
@@ -1838,6 +1872,10 @@
     gap: var(--tai-space-4);
   }
 
+  .tai-stack-1 {
+    gap: var(--tai-space-1);
+  }
+
   .tai-stack-2 {
     gap: var(--tai-space-2);
   }
@@ -2275,6 +2313,176 @@
     }
   }
 
+  /* -- Stepper: a flow's step progress. A 24 px marker per step, a 2 px connector
+     between steps (the ok fill after a done step), the label beside it. -- */
+  .tai-stepper {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    gap: var(--tai-space-2);
+    margin: 0;
+    padding: 0;
+    list-style: none;
+  }
+
+  .tai-stepper-step {
+    display: flex;
+    align-items: center;
+    gap: var(--tai-space-2);
+  }
+
+  .tai-stepper-step + .tai-stepper-step::before {
+    content: '';
+    display: block;
+    width: var(--tai-space-6);
+    height: 2px;
+    background: var(--tai-color-border);
+    transition: background-color var(--tai-motion-fast);
+  }
+
+  .tai-stepper-step-done + .tai-stepper-step::before {
+    background: var(--tai-color-ok-fill);
+  }
+
+  .tai-stepper-button {
+    display: inline-flex;
+    align-items: center;
+    gap: var(--tai-space-2);
+    min-width: 0;
+    padding: 0;
+    border: 0;
+    background: none;
+    font: inherit;
+    color: inherit;
+    overflow-wrap: anywhere;
+  }
+
+  button.tai-stepper-button {
+    cursor: pointer;
+    border-radius: var(--tai-radius-sm);
+  }
+
+  .tai-stepper-marker {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    flex-shrink: 0;
+    width: 24px;
+    height: 24px;
+    border-radius: 50%;
+    font-size: var(--tai-text-sm);
+    font-weight: 600;
+    transition:
+      background-color var(--tai-motion-fast),
+      box-shadow var(--tai-motion-fast),
+      color var(--tai-motion-fast);
+  }
+
+  .tai-stepper-marker > svg {
+    width: 14px;
+    height: 14px;
+  }
+
+  .tai-stepper-marker-done {
+    background: var(--tai-color-ok-fill);
+    color: var(--tai-color-on-fill);
+  }
+
+  .tai-stepper-marker-current {
+    box-shadow: inset 0 0 0 2px var(--tai-color-heading);
+    color: var(--tai-color-heading);
+  }
+
+  .tai-stepper-marker-upcoming {
+    box-shadow: inset 0 0 0 1px var(--tai-color-border-strong);
+    color: var(--tai-color-text-muted);
+  }
+
+  .tai-stepper-marker-error {
+    background: var(--tai-color-err-fill);
+    color: var(--tai-color-on-fill);
+  }
+
+  .tai-stepper-step-current .tai-stepper-label {
+    font-weight: 600;
+  }
+
+  .tai-stepper-step-upcoming .tai-stepper-label {
+    color: var(--tai-color-text-muted);
+  }
+
+  /* The "Step 2 of 3: " prefix is the narrow layout's; the wide row shows every step. */
+  .tai-stepper-position {
+    display: none;
+  }
+
+  /* -- ActionMenu: an overflow menu stacked in flow under its trigger. -- */
+  .tai-action-menu {
+    position: relative;
+    display: inline-block;
+  }
+
+  .tai-action-menu-list {
+    position: absolute;
+    inset-inline-end: 0;
+    top: calc(100% + var(--tai-space-1));
+    z-index: var(--tai-z-dropdown);
+    display: flex;
+    flex-direction: column;
+    min-width: 10rem;
+    padding: var(--tai-space-1);
+    border: 1px solid var(--tai-color-border);
+    border-radius: var(--tai-radius-md);
+    background: var(--tai-color-surface-raised);
+    box-shadow: var(--tai-shadow-lift);
+  }
+
+  .tai-action-menu-item {
+    display: flex;
+    align-items: center;
+    min-width: 0;
+    padding: var(--tai-space-2) var(--tai-space-3);
+    border: 0;
+    border-radius: var(--tai-radius-sm);
+    background: none;
+    font: inherit;
+    font-size: var(--tai-text-md);
+    color: var(--tai-color-text);
+    text-align: start;
+    overflow-wrap: anywhere;
+    cursor: pointer;
+  }
+
+  .tai-action-menu-item:hover,
+  .tai-action-menu-item:focus-visible {
+    background: var(--tai-color-surface);
+  }
+
+  .tai-action-menu-item-danger {
+    color: var(--tai-color-err-text);
+  }
+
+  /* <640: the stepper collapses to its current step, "Step 2 of 3: Pick tools";
+     the other steps stay in the list for assistive technology. */
+  @media (max-width: 639px) {
+    .tai-stepper-step:not(.tai-stepper-step-current) {
+      position: absolute;
+      width: 1px;
+      height: 1px;
+      overflow: hidden;
+      clip-path: inset(50%);
+      white-space: nowrap;
+    }
+
+    .tai-stepper-step + .tai-stepper-step::before {
+      display: none;
+    }
+
+    .tai-stepper-position {
+      display: inline;
+    }
+  }
+
   /* <640 phone: the rail gives way to a sticky 56 px top bar; the shell, the card
      grid and the page header each fall to a single column, and the page tightens
      its padding and its gap. */
@@ -2343,6 +2551,11 @@
       min-height: var(--tai-control-height-coarse);
     }
 
+    .tai-stepper-button,
+    .tai-action-menu-item {
+      min-height: var(--tai-control-height-coarse);
+    }
+
     .tai-icon-btn {
       width: var(--tai-control-height-coarse);
       height: var(--tai-control-height-coarse);
@@ -2417,6 +2630,11 @@
       transition: none;
     }
 
+    .tai-stepper-marker,
+    .tai-stepper-step + .tai-stepper-step::before {
+      transition: none;
+    }
+
     .tai-btn:hover:not(:disabled):not([aria-disabled='true']),
     .tai-card-interactive:hover,
     .tai-card-interactive:focus-within {