@ultimat3/ui 2.0.0 → 3.0.0

package/src/components/Tabs.tsx

@@ -4,6 +4,7 @@
 import type { JSX } from 'solid-js';
 import { ariaBool, createRovingTabindex, useId } from '../a11y';
 import { cx } from '../cx';
+import { TAB_SELECTOR, tabStopIndex } from '../roving';
 import { useUi } from '../theme/context';
 import styles from './Tabs.module.scss';
 
@@ -31,11 +32,20 @@ export function Tabs(props: TabsProps): JSX.Element {
   const base = useId('tabs');
   let list: HTMLDivElement | undefined;
 
+  // A disabled tab is excluded from BOTH answers — the list arrows walk and the one tab that
+  // carries the tab stop — because `focus()` on a disabled button silently does nothing, so a
+  // disabled tab left in the list pins the reducer on its index and hides every tab after it.
   const onKeyDown = createRovingTabindex(
-    () =>
-      list === undefined ? [] : Array.from(list.querySelectorAll<HTMLElement>('[role="tab"]')),
+    () => (list === undefined ? [] : Array.from(list.querySelectorAll<HTMLElement>(TAB_SELECTOR))),
     { orientation: props.orientation ?? 'horizontal', dir: ui.dir },
   );
+  // The selected tab holds the tab stop; a selected tab that is disabled, or a `value` matching no
+  // tab at all, falls back to the first enabled one rather than leaving the tablist unreachable.
+  const tabStop = (): number =>
+    tabStopIndex(
+      props.items,
+      props.items.findIndex((item) => item.id === props.value),
+    );
 
   return (
     <div
@@ -55,7 +65,7 @@ export function Tabs(props: TabsProps): JSX.Element {
         aria-orientation={props.orientation ?? 'horizontal'}
         onKeyDown={onKeyDown}
       >
-        {props.items.map((item) => (
+        {props.items.map((item, index) => (
           <button
             type="button"
             role="tab"
@@ -63,7 +73,7 @@ export function Tabs(props: TabsProps): JSX.Element {
             class={styles['tab']}
             aria-selected={ariaBool(props.value === item.id)}
             aria-controls={`${base}-panel-${item.id}`}
-            tabindex={props.value === item.id ? 0 : -1}
+            tabindex={index === tabStop() ? 0 : -1}
             disabled={item.disabled === true}
             onClick={() => props.onChange(item.id)}
           >

package/src/components/Toast.tsx

@@ -1,8 +1,11 @@
-// Transient notification. ToastRegion is the single live region for the app;
-// individual Toasts are its children, so announcements are not duplicated and
-// the region exists before the first message (screen readers require that).
+// Transient notification. ToastRegion is the single live region for the app; individual Toasts
+// are its children, so announcements are not duplicated and the region exists before the first
+// message. That ordering is the whole point: a live region created with its content already in it
+// is not announced by most screen readers, which is why `aria-live` sits on the persistent <ol>
+// here and NOT on the <li> each Toast renders.
 
 import type { JSX } from 'solid-js';
+import type { Politeness } from '../a11y';
 import { cx } from '../cx';
 import { UI_KEYS } from '../i18n-keys';
 import { useUi } from '../theme/context';
@@ -14,11 +17,20 @@ export interface ToastRegionProps {
   children: JSX.Element;
   /** Already-translated landmark name, e.g. "Notifications". */
   label: string;
+  /**
+   * How the region announces. `polite` waits for a pause and is right for everything an app
+   * routinely confirms; `assertive` interrupts whatever the user is being read, so it belongs only
+   * to a region that carries errors alone. One region, one politeness — mixing tones inside one
+   * list cannot work, because the live semantics belong to the list, not to the message.
+   */
+  politeness?: Politeness | undefined;
   placement?: 'block-end-inline-end' | 'block-start-inline-end' | 'block-end-center' | undefined;
   class?: string | undefined;
 }
 
 export function ToastRegion(props: ToastRegionProps): JSX.Element {
+  // `aria-atomic="false"` on the list: only the toast that was just added is read, never the whole
+  // list again on every arrival.
   return (
     <section
       class={cx(
@@ -28,7 +40,9 @@ export function ToastRegion(props: ToastRegionProps): JSX.Element {
       )}
       aria-label={props.label}
     >
-      <ol class={styles['list']}>{props.children}</ol>
+      <ol class={styles['list']} aria-live={props.politeness ?? 'polite'} aria-atomic="false">
+        {props.children}
+      </ol>
     </section>
   );
 }
@@ -47,14 +61,12 @@ export interface ToastProps {
 export function Toast(props: ToastProps): JSX.Element {
   const ui = useUi();
   const tone = (): Tone => props.tone ?? 'neutral';
-  const assertive = (): boolean => tone() === 'danger';
 
+  // No `role` and no `aria-live`: the enclosing ToastRegion owns both. `role="status"` here would
+  // also strip the element's `listitem` semantics, so the <ol> around it would announce a list of
+  // nothing. A danger toast belongs in a ToastRegion declared `politeness="assertive"`.
   return (
-    <li
-      class={cx(styles['toast'], styles[`tone-${tone()}`], props.class)}
-      role={assertive() ? 'alert' : 'status'}
-      aria-live={assertive() ? 'assertive' : 'polite'}
-    >
+    <li class={cx(styles['toast'], styles[`tone-${tone()}`], props.class)}>
       <div class={styles['content']}>
         {props.title === undefined ? null : <p class={styles['title']}>{props.title}</p>}
         <div class={styles['body']}>{props.children}</div>

package/src/components/Toolbar.tsx

@@ -1,6 +1,8 @@
 // The control strip above a table or a list: filters and search at the inline start, actions at
 // the inline end. `role="toolbar"` with the same roving-tabindex helper Tabs uses, so arrow keys
-// move between controls and the strip costs one Tab stop instead of a dozen.
+// move between the strip's buttons. It is NOT one tab stop: the strip holds arbitrary children it
+// cannot reach into to set an initial `tabindex`, and a search field at the inline start keeps its
+// own arrow keys, so making the strip a single stop would strand every control past it.
 
 import type { JSX } from 'solid-js';
 import { createRovingTabindex, focusableWithin } from '../a11y';
@@ -24,7 +26,9 @@ export function Toolbar(props: ToolbarProps): JSX.Element {
   const ui = useUi();
   let strip: HTMLDivElement | undefined;
 
-  // Arrows follow the writing direction; `focusableWithin` skips anything hidden or disabled.
+  // Arrows follow the writing direction; `focusableWithin` skips anything hidden or disabled, and
+  // `createRovingTabindex` declines outright while a control that answers arrows itself — the
+  // search Input this strip exists to hold — has focus.
   const onKeyDown = createRovingTabindex(
     () => (strip === undefined ? [] : focusableWithin(strip)),
     { orientation: 'horizontal', dir: ui.dir, loop: false },

package/src/components/file-input-view.ts

@@ -100,3 +100,28 @@ export function formatBytes(bytes: number, locale: string): string {
     maximumFractionDigits: index === 0 ? 0 : 1,
   }).format(value);
 }
+
+/** The one field of the `<input type="file">` a drop has to write. Structural, so a test needs no DOM. */
+export interface FileTarget {
+  files: FileList | null;
+}
+
+/**
+ * Hand a drop's files to the real `<input>`, so a dropped file behaves exactly like a picked one.
+ *
+ * Without this a `<Dropzone name="avatar" required>` inside a `<form>` shows the accepted file and
+ * then refuses to submit: `onSelect` fired, but `input.files` is still empty, so `required` blocks
+ * on "Please select a file" and a submit that got past it would post no file at all. Native form
+ * participation is what the `name`/`required` props promise. `files` is assignable from a
+ * `DataTransfer`'s own `FileList` in every current engine — that is the supported way to do this.
+ */
+export function adoptDroppedFiles(
+  input: FileTarget | undefined,
+  dropped: FileList | null | undefined,
+): void {
+  // An empty drop must not CLEAR a previous pick: the browser does not, and neither does this.
+  if (input === undefined || dropped === null || dropped === undefined || dropped.length === 0) {
+    return;
+  }
+  input.files = dropped;
+}

package/src/errors.ts

@@ -129,3 +129,18 @@ export function invalidValueError(kind: string, value: unknown, expected: string
     fix: `pass ${expected} — parse or validate the value in the loader, not in the component`,
   });
 }
+
+/**
+ * The icon generator was handed upstream data it cannot turn into a glyph module. No new code:
+ * malformed data is exactly what X_UI_INVALID_VALUE already names, and a code is stable forever
+ * once shipped. It is NOT X_UI_RUNTIME_MISSING, which says a host capability is absent and sends
+ * an operator to audit their environment for a fault that is in the file they just downloaded.
+ * The generator's environment faults — no network, no biome binary — keep that code.
+ */
+export function invalidIconDataError(found: string, fix: string): UiError {
+  return new UiError({
+    code: UI_ERROR_CODES.invalidValue,
+    cause: `lucide icon data ${found}`,
+    fix,
+  });
+}

package/src/fake-dom.ts

@@ -0,0 +1,194 @@
+// TEST-ONLY. A DOM small enough to read and real enough to run this package's keyboard code
+// against: focus that a disabled control silently refuses, `document.activeElement`, `contains`,
+// and `querySelectorAll` for the selector grammar these helpers actually pass. Not exported from
+// `index.ts` — the alternative is a DOM dependency, and the bugs it catches are the ones that only
+// exist because nothing ever called `createRovingTabindex` with elements attached.
+
+/** The subset of a selector these helpers use: comma groups of tag + `[attr]` + `:not(...)`. */
+const PART = /\[[^\]]*\]|:not\([^)]*\)/g;
+
+function attrMatches(element: FakeElement, test: string): boolean {
+  const inner = test.slice(1, -1);
+  const eq = inner.indexOf('=');
+  if (eq === -1) return element.getAttribute(inner) !== null;
+  const name = inner.slice(0, eq);
+  const value = inner.slice(eq + 1).replace(/^["']|["']$/g, '');
+  return element.getAttribute(name) === value;
+}
+
+function compoundMatches(element: FakeElement, compound: string): boolean {
+  const tag = compound.split(/[[:]/, 1)[0] ?? '';
+  if (tag !== '' && tag !== element.tagName.toLowerCase()) return false;
+  for (const part of compound.slice(tag.length).match(PART) ?? []) {
+    const ok = part.startsWith(':not(')
+      ? !attrMatches(element, part.slice(5, -1))
+      : attrMatches(element, part);
+    if (!ok) return false;
+  }
+  return true;
+}
+
+/** Listener book shared by the element and the document: registration only, and NO bubbling — a
+ * listener on a node never sees an event dispatched somewhere else, which is the whole point of
+ * the question `createFocusTrap` gets wrong. */
+class Listeners {
+  readonly listeners = new Map<string, Set<(event: unknown) => void>>();
+
+  addEventListener(type: string, handler: (event: unknown) => void): void {
+    const set = this.listeners.get(type) ?? new Set();
+    set.add(handler);
+    this.listeners.set(type, set);
+  }
+
+  removeEventListener(type: string, handler: (event: unknown) => void): void {
+    this.listeners.get(type)?.delete(handler);
+  }
+
+  dispatch(type: string, event: unknown): void {
+    for (const handler of [...(this.listeners.get(type) ?? [])]) handler(event);
+  }
+}
+
+const NATIVELY_FOCUSABLE = new Set(['BUTTON', 'INPUT', 'SELECT', 'TEXTAREA', 'SUMMARY']);
+const LINK_TAGS = new Set(['A', 'AREA']);
+
+/** An element that behaves like the real thing in the two ways this package's bugs depend on. */
+export class FakeElement extends Listeners {
+  readonly tagName: string;
+  readonly children: FakeElement[] = [];
+  parent: FakeElement | null = null;
+  readonly attrs: Record<string, string>;
+  /** Test assertion surface: how many times focus actually landed here. */
+  focusCount = 0;
+  owner: FakeDocument | null = null;
+
+  constructor(tagName: string, attrs: Record<string, string> = {}) {
+    super();
+    this.tagName = tagName.toUpperCase();
+    this.attrs = { ...attrs };
+  }
+
+  get tabIndex(): number {
+    return Number.parseInt(this.attrs['tabindex'] ?? '-1', 10);
+  }
+
+  set tabIndex(value: number) {
+    this.attrs['tabindex'] = String(value);
+  }
+
+  getAttribute(name: string): string | null {
+    return this.attrs[name] ?? null;
+  }
+
+  append(...children: readonly FakeElement[]): FakeElement {
+    for (const child of children) {
+      child.parent = this;
+      this.children.push(child);
+    }
+    return this;
+  }
+
+  /** The bug's mechanism, faithfully: focusing a disabled control does NOTHING and reports nothing.
+   * A tag that is not natively focusable and carries no `tabindex` refuses in exactly the same
+   * silence — `<div>.focus()` is the no-op behind the focus trap's empty-panel fallback. */
+  focus(): void {
+    if (this.getAttribute('disabled') !== null) return;
+    // `tabindex="-1"` IS focusable programmatically; it is only out of the TAB order.
+    const declared = this.getAttribute('tabindex') !== null;
+    if (!declared && !this.nativelyFocusable()) return;
+    this.focusCount += 1;
+    const doc = this.document();
+    if (doc !== null) doc.activeElement = this;
+  }
+
+  contains(node: unknown): boolean {
+    for (let at = node as FakeElement | null; at !== null; at = at.parent) {
+      if (at === this) return true;
+    }
+    return false;
+  }
+
+  descendants(): FakeElement[] {
+    return this.children.flatMap((child) => [child, ...child.descendants()]);
+  }
+
+  querySelectorAll(selector: string): FakeElement[] {
+    const groups = selector.split(',').map((one) => one.trim());
+    return this.descendants().filter((el) => groups.some((one) => compoundMatches(el, one)));
+  }
+
+  // `focusableWithin` filters on visibility; nothing in a fake tree is laid out, so everything is
+  // visible — a hidden-element rule would be this harness inventing a fact, not testing one.
+  readonly offsetParent: unknown = null;
+
+  getClientRects(): readonly unknown[] {
+    return [{}];
+  }
+
+  /** Focusable with no `tabindex` at all. `A`/`AREA` only with an `href` — the same condition
+   * `FOCUSABLE_SELECTOR` spells `a[href]`. */
+  private nativelyFocusable(): boolean {
+    if (NATIVELY_FOCUSABLE.has(this.tagName)) return true;
+    return LINK_TAGS.has(this.tagName) && this.getAttribute('href') !== null;
+  }
+
+  private document(): FakeDocument | null {
+    for (let at: FakeElement | null = this; at !== null; at = at.parent) {
+      if (at.owner !== null) return at.owner;
+    }
+    return null;
+  }
+}
+
+export interface FakeKeyboardEvent {
+  readonly key: string;
+  readonly shiftKey: boolean;
+  defaultPrevented: boolean;
+  preventDefault(): void;
+}
+
+export function keydown(key: string, shiftKey = false): FakeKeyboardEvent {
+  return {
+    key,
+    shiftKey,
+    defaultPrevented: false,
+    preventDefault(): void {
+      this.defaultPrevented = true;
+    },
+  };
+}
+
+export class FakeDocument extends Listeners {
+  activeElement: FakeElement | null = null;
+}
+
+export interface InstalledDom {
+  readonly document: FakeDocument;
+  readonly restore: () => void;
+}
+
+/**
+ * Publish `document` and `HTMLElement` globally for the duration of one test. Both are needed:
+ * `createRovingTabindex` reads `document.activeElement` and narrows it with `instanceof
+ * HTMLElement`, so a fake that is not the global class is silently treated as "focus is nowhere".
+ * ALWAYS restored — `solid()` decides a render is a server render by `document` being absent, and
+ * a leaked one turns every later component test in the process into `X_UI_RUNTIME_MISSING`.
+ */
+export function installFakeDom(root: FakeElement): InstalledDom {
+  const document = new FakeDocument();
+  root.owner = document;
+  const hadDocument = 'document' in globalThis;
+  const hadElement = 'HTMLElement' in globalThis;
+  const previousDocument: unknown = Reflect.get(globalThis, 'document');
+  const previousElement: unknown = Reflect.get(globalThis, 'HTMLElement');
+  Object.assign(globalThis, { document, HTMLElement: FakeElement });
+  return {
+    document,
+    restore(): void {
+      if (hadDocument) Object.assign(globalThis, { document: previousDocument });
+      else Reflect.deleteProperty(globalThis, 'document');
+      if (hadElement) Object.assign(globalThis, { HTMLElement: previousElement });
+      else Reflect.deleteProperty(globalThis, 'HTMLElement');
+    },
+  };
+}

package/src/icons/build-icons.ts

@@ -3,9 +3,10 @@
 // icons, so an upstream fix is a version bump plus a re-run and never a hand edit.
 
 import { rm } from 'node:fs/promises';
+import { renderCauseValue } from '@ultimat3/core';
 import type { IconGlyph } from '../components/icon-glyph';
 import { iconElements } from '../components/icon-glyph';
-import { runtimeMissingError } from '../errors';
+import { invalidIconDataError, runtimeMissingError } from '../errors';
 
 /** Pinned: a floating version would silently redraw icons under an app that never asked. */
 export const LUCIDE_VERSION = '1.31.0';
@@ -29,9 +30,9 @@ export function parseIconNodes(text: string): ReadonlyMap<string, IconGlyph> {
   const parsed: unknown = JSON.parse(text);
   // `typeof [] === 'object'`, and an array of icons is a different upstream format, not this one.
   if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
-    throw runtimeMissingError(
-      'lucide icon-nodes.json as an object',
-      `check ${LUCIDE_ICON_NODES_URL} is reachable, then re-run: bun run --filter @ultimat3/ui icons`,
+    throw invalidIconDataError(
+      `parsed as ${renderCauseValue(parsed)}, not the object of name to nodes that icon-nodes.json publishes; ${LUCIDE_ICON_NODES_URL} served something else`,
+      'bun run --filter @ultimat3/ui icons',
     );
   }
   const out = new Map<string, IconGlyph>();
@@ -41,6 +42,13 @@ export function parseIconNodes(text: string): ReadonlyMap<string, IconGlyph> {
   return out;
 }
 
+/**
+ * Glyph geometry, as characters: digits, the path-command letters, `currentColor`/`none`, and the
+ * separators between them. Deliberately not "anything that is not a quote" — an allowlist over a
+ * value bound for a code sink is the only shape that stays correct when the sink changes.
+ */
+export const SAFE_ATTR_VALUE = /^[\w\s.,+-]*$/;
+
 function toGlyph(name: string, value: unknown): IconGlyph {
   const glyph: (readonly [string, Readonly<Record<string, string>>])[] = [];
   for (const node of Array.isArray(value) ? (value as unknown[]) : []) {
@@ -48,7 +56,20 @@ function toGlyph(name: string, value: unknown): IconGlyph {
     const attrs: Record<string, string> = {};
     for (const [key, item] of Object.entries((node[1] ?? {}) as Record<string, unknown>)) {
       // Upstream keys an element for its diff tooling; it is not an SVG attribute.
-      if (key !== 'key') attrs[key] = String(item);
+      if (key === 'key') continue;
+      const text = String(item);
+      // Defence in depth behind `moduleSource`'s escaping: geometry is digits, path commands and
+      // separators, so anything else in a value that is about to be written into a TYPESCRIPT
+      // module is refused here rather than escaped and shipped. Measured against the whole
+      // committed set — all 1767 glyphs pass (`build-icons.test.ts` asserts it), so this rejects
+      // no legitimate Lucide artwork.
+      if (!SAFE_ATTR_VALUE.test(text)) {
+        throw invalidIconDataError(
+          `for the icon "${name}" carries ${renderCauseValue(text)} as "${key}", which is not glyph geometry; lucide-static@${LUCIDE_VERSION} is the pin that published it, so a re-run against the same pin repeats this`,
+          'bun run --filter @ultimat3/ui icons   # after raising LUCIDE_VERSION in packages/ui/src/icons/build-icons.ts',
+        );
+      }
+      attrs[key] = text;
     }
     glyph.push([node[0], attrs]);
   }
@@ -56,17 +77,25 @@ function toGlyph(name: string, value: unknown): IconGlyph {
   // would throw in a page is a build failure here instead.
   iconElements(glyph);
   if (glyph.length === 0) {
-    throw runtimeMissingError(
-      `renderable node data for the lucide icon "${name}"`,
-      `bump LUCIDE_VERSION in packages/ui/src/icons/build-icons.ts, then: bun run --filter @ultimat3/ui icons`,
+    throw invalidIconDataError(
+      `for the icon "${name}" carries no renderable node data; lucide-static@${LUCIDE_VERSION} is the pin that published it, so a re-run against the same pin repeats this`,
+      'bun run --filter @ultimat3/ui icons   # after raising LUCIDE_VERSION in packages/ui/src/icons/build-icons.ts',
     );
   }
   return glyph;
 }
 
+/**
+ * `JSON.stringify`, never `'${value}'`. The value is network-fetched data on its way into a
+ * TypeScript module that every app importing that icon will EXECUTE at import — a code sink, not
+ * an attribute sink. A raw quote in the value ends the string literal, and `');` after it starts
+ * a statement. `JSON.stringify` escapes quotes, backslashes and control characters, and Biome
+ * rewrites the quote style afterwards (`format()` below), so the committed output is unchanged.
+ * The key needs no escaping: `iconElements` has already refused every name off the allowlist.
+ */
 const attrsSource = (attrs: Readonly<Record<string, string>>): string =>
   Object.entries(attrs)
-    .map(([key, value]) => `${/^[a-z]+$/.test(key) ? key : `'${key}'`}: '${value}'`)
+    .map(([key, value]) => `${/^[a-z]+$/.test(key) ? key : `'${key}'`}: ${JSON.stringify(value)}`)
     .join(', ');
 
 /** One module's full text. Biome reformats it afterwards, so the layout here is only a seed. */

package/src/index.ts

@@ -83,9 +83,11 @@ export type {
   FileRejectionReason,
   FileSelection,
   FileSelectionLimits,
+  FileTarget,
 } from './components/file-input-view';
 export {
   acceptMatches,
+  adoptDroppedFiles,
   formatBytes,
   progressPercent,
   selectFiles,
@@ -178,6 +180,7 @@ export type { UiErrorCode } from './errors';
 export {
   invalidBrandTokenError,
   invalidGlyphError,
+  invalidIconDataError,
   invalidThemeError,
   invalidValueError,
   providerNeedsRuntimeError,
@@ -188,6 +191,13 @@ export {
 } from './errors';
 export type { UiKey } from './i18n-keys';
 export { UI_KEYS } from './i18n-keys';
+export type { ArrowKeyElement, RovingItem } from './roving';
+export {
+  handlesOwnArrowKeys,
+  MENU_ITEM_SELECTOR,
+  TAB_SELECTOR,
+  tabStopIndex,
+} from './roving';
 export type { Brand, BrandInput, FontSlot } from './theme/brand';
 export { brandStyleCspSource, brandStyleTag, defineTheme, FONT_SLOTS } from './theme/brand';
 export type { Direction, UiContextValue } from './theme/context';

package/src/jsx-probe.ts

@@ -0,0 +1,125 @@
+// TEST-ONLY. Calls a component and walks what it returned, so a test can assert on the props an
+// element actually carries — the `tabindex`, the `aria-live`, the `onKeyDown`, the `ref` — rather
+// than on a string it was serialised into. Complements `theme/inert-render.test.ts`, which asks
+// the other question (does the markup come out at all).
+//
+// Which JSX factory a `.tsx` in this package compiled to is NOT ours to choose: `@ultimat3/render`
+// installs a process-global `Bun.plugin` `onLoad` for `/\.tsx$/` at import, and `bun test` is one
+// process. Both factories build the same shape — a `type`, a `props`, children under
+// `props.children` — so this walker recognises both and the run's file order stops deciding.
+
+const RENDER_NODE: symbol = Symbol.for('ultimate.render.jsx');
+
+export interface ProbeNode {
+  readonly type: string | ((props: Record<string, unknown>) => unknown);
+  readonly props: Record<string, unknown>;
+}
+
+export function isProbeNode(value: unknown): value is ProbeNode {
+  if (typeof value !== 'object' || value === null) return false;
+  return 'inert' in value || RENDER_NODE in value;
+}
+
+function h(
+  type: ProbeNode['type'],
+  props: Record<string, unknown> | null,
+  ...children: readonly unknown[]
+): ProbeNode {
+  const base = { ...(props ?? {}) };
+  if (children.length > 0) base['children'] = children.length === 1 ? children[0] : children;
+  return { inert: true, type, props: base } as unknown as ProbeNode;
+}
+
+/**
+ * How many probes are live, and what `globalThis.React` was before the first one. A harness that
+ * DELETED the property on the way out destroyed a binding it did not create, and a nested or
+ * repeated probe tore the factory out from under the suite still using it — the counter is what
+ * makes the last unprobe the only one that restores.
+ */
+let depth = 0;
+let saved: PropertyDescriptor | undefined;
+
+/** Install the classic-factory global these `.tsx` files fall back to. Paired with `unprobe()`. */
+export function probe(): void {
+  if (depth === 0) {
+    // The descriptor, not the value: the property may be a getter or non-writable, and `assign`
+    // onto either throws or silently loses. `defineProperty` installs over both.
+    saved = Object.getOwnPropertyDescriptor(globalThis, 'React');
+    Object.defineProperty(globalThis, 'React', {
+      value: { createElement: h },
+      configurable: true,
+      writable: true,
+      enumerable: true,
+    });
+  }
+  depth += 1;
+}
+
+/** Undo the matching `probe()`. Unbalanced calls are inert: nothing this did not install is torn
+ * down, because the binding at depth 0 belongs to somebody else. */
+export function unprobe(): void {
+  if (depth === 0) return;
+  depth -= 1;
+  if (depth > 0) return;
+  if (saved === undefined) Reflect.deleteProperty(globalThis, 'React');
+  else Object.defineProperty(globalThis, 'React', saved);
+  saved = undefined;
+}
+
+/**
+ * Every host node in the tree, depth first, with nested components CALLED. Thunks are called too:
+ * a component that reads a prop inside one renders nothing until something asks.
+ */
+export function nodesOf(value: unknown): ProbeNode[] {
+  if (value === null || value === undefined || typeof value === 'boolean') return [];
+  if (typeof value === 'string' || typeof value === 'number') return [];
+  if (Array.isArray(value)) return value.flatMap(nodesOf);
+  if (isProbeNode(value)) {
+    if (typeof value.type === 'function') return nodesOf(value.type(value.props));
+    return [value, ...nodesOf(value.props['children'])];
+  }
+  if (typeof value === 'function') return nodesOf((value as () => unknown)());
+  return [];
+}
+
+/** Render a component to its host nodes. `props` is the component's own, untyped on purpose. */
+export function renderNodes(component: unknown, props: Record<string, unknown> = {}): ProbeNode[] {
+  return nodesOf((component as (p: Record<string, unknown>) => unknown)(props));
+}
+
+const attr = (node: ProbeNode, name: string): unknown => node.props[name];
+
+/** Nodes whose attribute equals `value`; `undefined` matches "carries the attribute at all". */
+export function withAttr(nodes: readonly ProbeNode[], name: string, value?: unknown): ProbeNode[] {
+  return nodes.filter((node) =>
+    value === undefined ? attr(node, name) !== undefined : attr(node, name) === value,
+  );
+}
+
+export function byTag(nodes: readonly ProbeNode[], tag: string): ProbeNode[] {
+  return nodes.filter((node) => node.type === tag);
+}
+
+/** The one node a test means, or a throw naming what it looked for — never a silent `undefined`. */
+export function one(nodes: readonly ProbeNode[], what: string): ProbeNode {
+  const node = nodes[0];
+  if (node === undefined || nodes.length !== 1) {
+    throw new Error(`expected exactly one ${what}, found ${nodes.length}`);
+  }
+  return node;
+}
+
+/** Call an element's `ref` prop with the element a test built for it. */
+export function attachRef(node: ProbeNode, element: unknown): void {
+  const ref = node.props['ref'];
+  if (typeof ref !== 'function') throw new Error(`node <${String(node.type)}> carries no ref`);
+  (ref as (el: unknown) => void)(element);
+}
+
+/** Call an element's event handler prop, e.g. `fire(menu, 'onKeyDown', keydown('ArrowDown'))`. */
+export function fire(node: ProbeNode, handler: string, event: unknown): void {
+  const fn = node.props[handler];
+  if (typeof fn !== 'function')
+    throw new Error(`node <${String(node.type)}> carries no ${handler}`);
+  (fn as (e: unknown) => void)(event);
+}