@matchstick-trading/primitives 0.0.10

package/src/StudiesParts.tsx

@@ -0,0 +1,226 @@
+import { createContext, useCallback, useContext, useEffect, useId, useMemo, useState, type ReactNode } from 'react';
+import { useChart } from './ChartParts.js';
+import { resolveSeries, type SeriesPoint } from './core/series.js';
+import { SelectionContext } from './selection-context.js';
+
+/**
+ * Study as parts: Root, Line, Band, Legend. Line and Band go inside `Chart.Plot` and draw a study's values on the
+ * price scale; they read the frame through useChart(). A Legend outside the SVG lists each study and its value at the
+ * crosshair bar, so the numbers are text and not only a picture.
+ *
+ * Wrap `Chart.Plot` and the Legend in one `Study.Root`: the lines tell it their name and values, and the Legend reads
+ * them back. Without a Root the lines still draw and the Legend is empty. Keep a study's values in a `useMemo`; a
+ * new array each render only costs a re-registration, never a loop.
+ */
+interface Entry {
+  name: string;
+  /** One series for a line; [lower, upper] for a band. */
+  series: ReadonlyArray<ReadonlyArray<number | null>>;
+  /** The selection id, when the study has one and a Selection.Root is above. */
+  selectId?: string;
+  /** What is wrong with the series, in words; the Legend shows it. */
+  problems?: readonly string[];
+}
+interface Registry {
+  register: (id: string, entry: Entry) => void;
+  unregister: (id: string) => void;
+}
+const RegistryContext = createContext<Registry | null>(null);
+const EntriesContext = createContext<ReadonlyMap<string, Entry>>(new Map());
+
+/** Keeps the studies' names and values so the Legend can list them. Draws nothing. */
+function Root({ children }: { children?: ReactNode }) {
+  const [entries, setEntries] = useState<ReadonlyMap<string, Entry>>(() => new Map());
+  const register = useCallback((id: string, entry: Entry) => {
+    setEntries((current) => {
+      const next = new Map(current);
+      next.set(id, entry);
+      return next;
+    });
+  }, []);
+  const unregister = useCallback((id: string) => {
+    setEntries((current) => {
+      if (!current.has(id)) return current;
+      const next = new Map(current);
+      next.delete(id);
+      return next;
+    });
+  }, []);
+  const registry = useMemo<Registry>(() => ({ register, unregister }), [register, unregister]);
+  return (
+    <RegistryContext.Provider value={registry}>
+      <EntriesContext.Provider value={entries}>{children}</EntriesContext.Provider>
+    </RegistryContext.Provider>
+  );
+}
+
+function useRegistration(name: string, series: Entry['series'], selectId?: string, problems?: readonly string[]) {
+  const registry = useContext(RegistryContext);
+  const id = useId();
+  useEffect(() => {
+    registry?.register(id, { name, series, selectId, problems });
+    return () => registry?.unregister(id);
+  }, [registry, id, name, series, selectId, problems]);
+}
+
+/** Wide enough for a finger: the transparent hit stroke is --mt-touch-target (44px) across. */
+const HIT_WIDTH = 44;
+
+/**
+ * Selection for a study with an `id`: whether it is selected, and the extra id the Legend needs. Without a Selection.Root
+ * above, or without an id, nothing is selectable and the study draws exactly as it did.
+ */
+function useStudySelection(id: string | undefined, name: string) {
+  const selection = useContext(SelectionContext);
+  const setName = selection?.setName;
+  useEffect(() => {
+    if (setName && id !== undefined && name) setName('study', id, name);
+  }, [setName, id, name]);
+  const selectId = selection && id !== undefined ? id : undefined;
+  const sel = selection?.selection;
+  const selected = selectId !== undefined && !!sel && sel.kind === 'study' && sel.id === selectId;
+  return { selectId, selected };
+}
+
+const num = (n: number) => n.toFixed(2);
+
+/** One run of consecutive bars first..last, as SVG path segments. `pick` returns a point for a bar or null to break the run. */
+function runs(first: number, last: number, pick: (i: number) => number | null): number[][] {
+  const out: number[][] = [];
+  let run: number[] = [];
+  for (let i = first; i <= last; i++) {
+    if (pick(i) === null) {
+      if (run.length) out.push(run);
+      run = [];
+    } else run.push(i);
+  }
+  if (run.length) out.push(run);
+  return out;
+}
+
+const valid = (v: number | null | undefined): v is number => v !== null && v !== undefined && Number.isFinite(v);
+
+export interface StudyLineProps {
+  /** The line on its own clock, placed on the bars by exact time. A bar with no point on it has no value there; a bar's gap kind (closed, missing, ...) is not drawn. */
+  points?: ReadonlyArray<SeriesPoint>;
+  /**
+   * One value per bar by position, null where the study has none. A study computed from these bars (`sma(bars, 20)`) is
+   * already by position. Give `points` for a series that comes from elsewhere. Neither given draws nothing.
+   * @deprecated Give `points` (`pointsFromValues(bars, sma(bars, 20))` makes them). `values` is removed in 0.0.7.
+   */
+  values?: ReadonlyArray<number | null>;
+  /** Shown in the Legend and carried as `data-study`. */
+  name: string;
+  /** Makes the study selectable (with a Selection.Root above): by a tap on the line and by its Legend button. Unique on the chart. */
+  id?: string;
+  className?: string;
+}
+
+/** A line through the study's values in view. It lifts the pen at every null, so a warm-up gap stays a gap. */
+const NO_VALUES: ReadonlyArray<number | null> = [];
+
+function Line({ values: given, points, name, id, className }: StudyLineProps) {
+  const { frame, readoutId, bars } = useChart('Study.Line');
+  // Points are placed on the bars by exact time; a study's own values are already one per bar.
+  const resolved = useMemo(() => {
+    if (points === undefined) {
+      if (given !== undefined) return { values: given, problems: [] as string[] };
+      return { values: NO_VALUES, problems: [`"${name}" has neither points nor values, so there is nothing to draw.`] };
+    }
+    const r = resolveSeries(bars.map((b) => b.timestamp), { id: id ?? name, label: name, points });
+    return { values: r.values, problems: r.problems };
+  }, [points, given, bars, id, name]);
+  const values = resolved.values;
+  const series = useMemo(() => [values], [values]);
+  const { selectId, selected } = useStudySelection(id, name);
+  useRegistration(name, series, selectId, resolved.problems);
+  let d = '';
+  for (const run of runs(frame.first, frame.last, (i) => (valid(values[i]) ? 0 : null))) {
+    if (run.length < 2) continue;
+    d += run.map((i, k) => `${k === 0 ? 'M' : 'L'}${num(frame.x(i))},${num(frame.y(values[i] as number))}`).join('');
+  }
+  if (!d) return null;
+  const line = <path className={className} data-part="study-line" data-state={selected ? 'selected' : undefined} clipPath={`url(#${readoutId}-price)`} data-study={name} d={d} fill="none" aria-hidden="true" />;
+  if (selectId === undefined) return line;
+  // A wide transparent stroke on top, so a finger can hit a thin line. The Selection.Layer reads the tap from `data-select-id`.
+  return (
+    <>
+      {line}
+      <path data-part="study-hit" data-select-id={selectId} clipPath={`url(#${readoutId}-price)`} d={d} fill="none" stroke="transparent" strokeWidth={HIT_WIDTH} strokeLinecap="round" strokeLinejoin="round" pointerEvents="stroke" aria-hidden="true" />
+    </>
+  );
+}
+
+export interface StudyBandProps {
+  upper: ReadonlyArray<number | null>;
+  lower: ReadonlyArray<number | null>;
+  /** Shown in the Legend as "lower - upper" and carried as `data-study`. Without a name the band is not listed. */
+  name?: string;
+  /** Makes the study selectable (with a Selection.Root above): by a tap on the band and, when it has a name, by its Legend button. Unique on the chart. */
+  id?: string;
+  className?: string;
+}
+
+/** The space between two series, filled. It stops where either series has no value. */
+function Band({ upper: givenUpper, lower: givenLower, name = '', id, className }: StudyBandProps) {
+  const upper = givenUpper ?? NO_VALUES; // a side that is not computed yet leaves the band empty
+  const lower = givenLower ?? NO_VALUES;
+  const { frame, readoutId } = useChart('Study.Band');
+  const series = useMemo(() => [lower, upper], [lower, upper]);
+  const { selectId, selected } = useStudySelection(id, name);
+  useRegistration(name, series, selectId);
+  let d = '';
+  const both = (i: number) => (valid(upper[i]) && valid(lower[i]) ? 0 : null);
+  for (const run of runs(frame.first, frame.last, both)) {
+    if (run.length < 2) continue;
+    const top = run.map((i, k) => `${k === 0 ? 'M' : 'L'}${num(frame.x(i))},${num(frame.y(upper[i] as number))}`).join('');
+    const bottom = [...run].reverse().map((i) => `L${num(frame.x(i))},${num(frame.y(lower[i] as number))}`).join('');
+    d += `${top}${bottom}Z`;
+  }
+  if (!d) return null;
+  const band = <path className={className} data-part="study-band" data-state={selected ? 'selected' : undefined} clipPath={`url(#${readoutId}-price)`} data-study={name || undefined} d={d} aria-hidden="true" />;
+  if (selectId === undefined) return band;
+  return (
+    <>
+      {band}
+      <path data-part="study-hit" data-select-id={selectId} clipPath={`url(#${readoutId}-price)`} d={d} fill="transparent" stroke="transparent" strokeWidth={HIT_WIDTH} strokeLinejoin="round" pointerEvents="all" aria-hidden="true" />
+    </>
+  );
+}
+
+export interface StudyLegendProps {
+  className?: string;
+  /** Prints one value. Default: the chart's decimals. */
+  format?: (value: number) => string;
+}
+
+/**
+ * The studies and their values at the crosshair bar (the last bar in view while there is no crosshair). Put it outside
+ * the SVG. `data-active` is present while the values belong to a crosshair bar. A study with no value there shows a dash.
+ */
+function Legend({ className, format }: StudyLegendProps) {
+  const { active, frame, decimals } = useChart('Study.Legend');
+  const entries = useContext(EntriesContext);
+  const selection = useContext(SelectionContext);
+  const index = active ?? frame.last;
+  const text = (v: number | null | undefined) => (valid(v) ? (format ? format(v) : v.toFixed(decimals)) : '–');
+  const items: ReactNode[] = [];
+  entries.forEach((entry, id) => {
+    if (!entry.name) return;
+    const selectId = selection ? entry.selectId : undefined;
+    const selected = selectId !== undefined && selection!.selection?.kind === 'study' && selection!.selection.id === selectId;
+    const name = <span data-part="study-name">{entry.name}</span>;
+    items.push(
+      <li key={id} data-part="study-legend-item" data-study={entry.name} data-state={selected ? 'selected' : undefined}>
+        {selectId === undefined ? name : (
+          <button type="button" data-mt="" data-touch-target="" data-part="study-select" aria-pressed={selected} onClick={() => selection!.select(selected ? null : { kind: 'study', id: selectId })}>{name}</button>
+        )}{' '}
+        <span data-part="study-value" data-mt-numeric>{entry.series.map((s) => text(s[index])).join(' – ')}</span>
+        {(entry.problems ?? []).map((p) => <span key={p} data-part="study-problem" role="note"> {p}</span>)}
+      </li>,
+    );
+  });
+  return <ul className={className} data-part="study-legend" data-active={active !== null ? '' : undefined} aria-label="Study values">{items}</ul>;
+}
+
+export { Root, Line, Band, Legend };

package/src/Submenu.tsx

@@ -0,0 +1,5 @@
+import { List, SubmenuRoot, SubmenuTrigger } from './MenuParts.js';
+
+// A submenu is a menu inside a menu. Its list and items are the Menu ones (Menu.List, Menu.Item); only the root and the
+// trigger differ. Built here, outside the client module, for the same reason as Menu.
+export const Submenu = { Root: SubmenuRoot, Trigger: SubmenuTrigger, List };

package/src/SymbolSearch.tsx

@@ -0,0 +1,6 @@
+import { Root, Input, List, Option, Count } from './SymbolSearchParts.js';
+
+// The parts live in SymbolSearchParts.js (a client module). The namespace object is built here, outside it, so a server
+// component can write `SymbolSearch.Root`: a property of an object exported from a client module is not reachable there.
+export * from './SymbolSearchParts.js';
+export const SymbolSearch = { Root, Input, List, Option, Count };

package/src/SymbolSearchParts.tsx

@@ -0,0 +1,166 @@
+import { createContext, useCallback, useContext, useId, useMemo, useState, type ChangeEvent, type KeyboardEvent, type ReactNode } from 'react';
+import { buildSymbolIndex, nextSymbolIndex, resolveSymbolKey, searchSymbols, type Instrument, type SymbolMatch } from './core/symbol-search.js';
+
+/**
+ * SymbolSearch as parts: Root, Input, List, Option, Count. Headless; a combobox over a list the host
+ * supplies. The host owns the instruments (and what a venue or a contract roll means); the parts own matching,
+ * keys and what a screen reader hears. Typing never throws, whatever the characters.
+ *
+ * Keys in the input: ArrowDown/ArrowUp move through the rows (they stop at the ends), Enter picks the highlighted
+ * row, Escape closes the list and a second Escape clears the text. The best match is highlighted as you type, so
+ * Enter alone takes it. The count is announced politely; each row says why it matched (symbol, alias or name).
+ */
+interface SearchContext {
+  query: string;
+  setQuery: (text: string) => void;
+  open: boolean;
+  setOpen: (open: boolean) => void;
+  rows: SymbolMatch[];
+  more: boolean;
+  active: number;
+  setActive: (index: number) => void;
+  pick: (index: number) => void;
+  listId: string;
+  countId: string;
+  optionId: (index: number) => string;
+}
+const Context = createContext<SearchContext | null>(null);
+
+function useSearch(part: string): SearchContext {
+  const context = useContext(Context);
+  if (!context) throw new Error(`SymbolSearch.${part} needs a SymbolSearch.Root above it.`);
+  return context;
+}
+
+export interface SymbolSearchRootProps {
+  instruments: readonly Instrument[];
+  /** Rows shown, 1 to 200; default 20. */
+  limit?: number;
+  venue?: string;
+  kind?: string;
+  /** True when the instrument list is synthetic; sets `data-synthetic` on the root. */
+  synthetic?: boolean;
+  onPick?: (instrument: Instrument) => void;
+  className?: string;
+  children?: ReactNode;
+}
+
+function Root({ instruments, limit = 20, venue, kind, synthetic, onPick, className, children }: SymbolSearchRootProps) {
+  const index = useMemo(() => buildSymbolIndex(instruments), [instruments]);
+  const [query, setQueryState] = useState('');
+  const [open, setOpen] = useState(false);
+  const [active, setActive] = useState(-1);
+  const id = useId();
+  const shown = Math.min(200, Math.max(1, Math.floor(limit) || 20));
+  const found = useMemo(() => searchSymbols(index, query, { limit: shown + 1, venue, kind }), [index, query, shown, venue, kind]);
+  const rows = found.slice(0, shown);
+  const more = found.length > shown;
+  const setQuery = useCallback((text: string) => {
+    setQueryState(text);
+    setOpen(text.trim() !== '');
+    setActive(text.trim() === '' ? -1 : 0); // the best match is highlighted, so Enter alone takes it
+  }, []);
+  const pick = useCallback((i: number) => {
+    const row = rows[i];
+    if (!row) return;
+    setQueryState(row.instrument.symbol);
+    setOpen(false);
+    setActive(-1);
+    onPick?.(row.instrument);
+  }, [rows, onPick]);
+  const context = useMemo<SearchContext>(() => ({
+    query, setQuery, open, setOpen, rows, more, active: active >= rows.length ? rows.length - 1 : active, setActive, pick,
+    listId: `${id}-list`, countId: `${id}-count`, optionId: (i) => `${id}-opt-${i}`,
+  }), [query, setQuery, open, rows, more, active, pick, id]);
+  return (
+    <Context.Provider value={context}>
+      <div className={className} data-synthetic={synthetic ? '' : undefined}>{children}</div>
+    </Context.Provider>
+  );
+}
+
+/** The text box. One tab stop; it owns the keys. */
+function Input({ className, label = 'Search instruments', placeholder }: { className?: string; label?: string; placeholder?: string }) {
+  const { query, setQuery, open, setOpen, rows, active, setActive, pick, listId, countId, optionId } = useSearch('Input');
+  const onKeyDown = (event: KeyboardEvent<HTMLInputElement>) => {
+    const action = resolveSymbolKey(event.nativeEvent, { open, hasText: query !== '' });
+    if (!action) return;
+    if (action === 'pick' && rows.length === 0) return;
+    event.preventDefault();
+    event.stopPropagation(); // these keys are not the page's transport shortcuts while the box has focus
+    if (action === 'next' || action === 'previous') {
+      if (!open && query.trim() !== '') setOpen(true);
+      setActive(nextSymbolIndex(rows.length, active, action));
+    } else if (action === 'pick') pick(Math.max(0, active));
+    else if (action === 'close') setOpen(false);
+    else setQuery('');
+  };
+  return (
+    <input
+      className={className}
+      type="text"
+      role="combobox"
+      aria-label={label}
+      aria-autocomplete="list"
+      aria-expanded={open && rows.length > 0}
+      aria-controls={listId}
+      aria-describedby={countId}
+      aria-activedescendant={open && active >= 0 && active < rows.length ? optionId(active) : undefined}
+      autoComplete="off"
+      autoCapitalize="characters"
+      spellCheck={false}
+      placeholder={placeholder}
+      value={query}
+      onChange={(event: ChangeEvent<HTMLInputElement>) => setQuery(event.target.value)}
+      onBlur={() => setOpen(false)}
+      onKeyDown={onKeyDown}
+    />
+  );
+}
+
+/** The result list, given the rows to draw. Hidden while closed or empty. */
+function List({ className, children }: { className?: string; children: (rows: SymbolMatch[]) => ReactNode }) {
+  const { rows, open, listId } = useSearch('List');
+  return (
+    <ul id={listId} className={className} role="listbox" aria-label="Matching instruments" hidden={!open || rows.length === 0}>
+      {open ? children(rows) : null}
+    </ul>
+  );
+}
+
+/** One row. `data-matched` says why it is here; `data-venue` keeps the same symbol on two venues apart. */
+function Option({ row, index, className, children }: { row: SymbolMatch; index: number; className?: string; children?: ReactNode }) {
+  const { active, pick, optionId } = useSearch('Option');
+  const { instrument } = row;
+  return (
+    <li
+      id={optionId(index)}
+      className={className}
+      role="option"
+      aria-selected={index === active}
+      data-matched={row.matchedOn}
+      data-venue={instrument.venue}
+      onMouseDown={(event) => event.preventDefault()} // keep focus in the box
+      onClick={() => pick(index)}
+    >
+      {children ?? (
+        <>
+          <span data-mt-numeric="">{instrument.symbol}</span> <span>{instrument.venue}</span>
+          {instrument.name && <> <span>{instrument.name}</span></>}
+          {row.matchedOn !== 'symbol' && <> <span>(matched {row.matchedOn})</span></>}
+        </>
+      )}
+    </li>
+  );
+}
+
+/** The count, announced politely: "3 results", "No instrument matches". Nothing while the box is empty. */
+function Count({ className }: { className?: string }) {
+  const { query, rows, more, countId } = useSearch('Count');
+  const text = query.trim() === '' ? ''
+    : rows.length === 0 ? `No instrument matches “${query.trim()}”.`
+      : `${rows.length}${more ? '+' : ''} ${rows.length === 1 && !more ? 'result' : 'results'}${more ? ', first rows shown' : ''}.`;
+  return <output id={countId} className={className} aria-live="polite">{text}</output>;
+}
+
+export { Root, Input, List, Option, Count };

package/src/Tape.tsx

@@ -0,0 +1,6 @@
+import { Root, Table, Header, Row, Time, Price, Size, Side, Summary, Status } from './TapeParts.js';
+
+// The parts live in TapeParts.js (a client module). The namespace object is built here, outside it, so a server
+// component can write `Tape.Root`: a property of an object exported from a client module is not reachable there.
+export * from './TapeParts.js';
+export const Tape = { Root, Table, Header, Row, Time, Price, Size, Side, Summary, Status };

package/src/TapeParts.tsx

@@ -0,0 +1,208 @@
+import { createContext, useContext, useEffect, useMemo, useRef, useState, type FocusEvent, type KeyboardEvent, type ReactNode } from 'react';
+import { TAPE_SIDE_LABEL, holdTape, newestFirst, nextTapeIndex, readTape, resolveTapeKey, tapeSummary, type TapeIssue, type TapeRow, type TapeTrade } from './core/tape.js';
+
+/**
+ * Tape as parts: Root, Table, Header, Row, Time, Price, Size, Side, Summary, Status. Headless: the parts are real
+ * table elements and add `data-tape-side` (buy in the bid colour with ▲, sell in the ask colour with ▼) and `data-paused`; the host
+ * chooses the columns.
+ *
+ * Newest first. While the pointer or focus is on the tape the rows hold their place and new trades are counted, not
+ * inserted, so a row never moves under a finger. Keys: arrows move between rows, Home is the newest row and End the
+ * oldest, Enter or Space picks the row. The Summary part is one polite line on a timer, never one announcement per
+ * trade. A row that breaks a rule is listed by Status and is not drawn.
+ */
+interface TapeContext {
+  issues: TapeIssue[];
+  paused: boolean;
+  waiting: number;
+  summary: string;
+  activeId: string | null;
+  firstId: string | null;
+  setActive: (id: string) => void;
+}
+const Context = createContext<TapeContext | null>(null);
+
+function useTape(part: string): TapeContext {
+  const context = useContext(Context);
+  if (!context) throw new Error(`Tape.${part} needs a Tape.Root above it.`);
+  return context;
+}
+
+export interface TapeRootProps {
+  /** The trades, oldest first. Anything that breaks a rule is reported by `Tape.Status` and left out. */
+  trades: readonly TapeTrade[];
+  /** How many of the newest rows to show. Default 50. */
+  limit?: number;
+  /** How often the summary line may change, in milliseconds. Default 5000. */
+  summaryEveryMs?: number;
+  /** Enter or Space on a focused row. */
+  onSelect?: (row: TapeRow) => void;
+  className?: string;
+  /** The parts, given the rows to show (newest first, held while the pointer or focus is on the tape). */
+  children: (rows: TapeRow[]) => ReactNode;
+}
+
+function Root({ trades, limit = 50, summaryEveryMs = 5000, onSelect, className, children }: TapeRootProps) {
+  const read = useMemo(() => readTape(trades), [trades]);
+  const [pointer, setPointer] = useState(false);
+  const [focus, setFocus] = useState(false);
+  const [held, setHeld] = useState<string[] | null>(null);
+  const [activeId, setActiveId] = useState<string | null>(null);
+  const root = useRef<HTMLDivElement>(null);
+
+  const live = useMemo(() => newestFirst(read.rows).slice(0, Math.max(0, limit)), [read.rows, limit]);
+  const paused = pointer || focus;
+  const holding = paused && held ? holdTape(held, read.rows) : null;
+  const shown = holding ? holding.rows : live;
+  const waiting = holding ? holding.waiting : 0;
+  const summary = useMemo(() => tapeSummary(read.rows), [read.rows]);
+  const firstId = shown.length ? shown[0].id : null;
+  // If the row last focused has left the shown rows, the tab stop goes back to the newest row.
+  const stopId = activeId !== null && shown.some((r) => r.id === activeId) ? activeId : null;
+
+  const freeze = () => setHeld((current) => current ?? live.map((r) => r.id));
+  const release = (next: boolean) => { if (!next) setHeld(null); };
+
+  const focusRow = (id: string) => {
+    setActiveId(id);
+    for (const tr of root.current?.querySelectorAll<HTMLElement>('tr[data-tape-row]') ?? []) {
+      if (tr.dataset.tapeRow === id) { tr.focus(); return; }
+    }
+  };
+
+  const onKeyDown = (event: KeyboardEvent<HTMLDivElement>) => {
+    const action = resolveTapeKey(event.nativeEvent);
+    if (!action) return;
+    const onRow = (event.target as HTMLElement).closest('tr[data-tape-row]') as HTMLElement | null;
+    if (!onRow) return;
+    if (action.type === 'select') {
+      if (event.target !== onRow) return; // a control inside the row keeps its own Enter and Space
+      const row = shown.find((r) => r.id === onRow.dataset.tapeRow);
+      if (!row || !onSelect) return;
+      event.preventDefault();
+      onSelect(row);
+      return;
+    }
+    event.preventDefault();
+    event.stopPropagation(); // these keys are also page shortcuts
+    const index = shown.findIndex((r) => r.id === onRow.dataset.tapeRow);
+    const to = nextTapeIndex(shown.length, index, action.to);
+    if (to >= 0) focusRow(shown[to].id);
+  };
+
+  const onBlur = (event: FocusEvent<HTMLDivElement>) => {
+    if (event.currentTarget.contains(event.relatedTarget as Node | null)) return;
+    setFocus(false);
+    release(pointer);
+  };
+
+  // A focused row that the host's window drops leaves the page without a blur event, so let go of the hold here.
+  useEffect(() => {
+    if (focus && root.current && !root.current.contains(document.activeElement)) {
+      setFocus(false);
+      if (!pointer) setHeld(null);
+    }
+  }, [shown, focus, pointer]);
+
+  // The summary changes on a timer, and not at all while someone is reading rows.
+  const latest = useRef(summary);
+  latest.current = summary;
+  const pausedRef = useRef(paused);
+  pausedRef.current = paused;
+  const [announced, setAnnounced] = useState(summary);
+  useEffect(() => {
+    const id = setInterval(() => { if (!pausedRef.current) setAnnounced(latest.current); }, Math.max(1000, summaryEveryMs));
+    return () => clearInterval(id);
+  }, [summaryEveryMs]);
+
+  const context = useMemo<TapeContext>(
+    () => ({ issues: read.issues, paused, waiting, summary: announced, activeId: stopId, firstId, setActive: setActiveId }),
+    [read.issues, paused, waiting, announced, stopId, firstId],
+  );
+  return (
+    <Context.Provider value={context}>
+      <div
+        ref={root}
+        className={className}
+        data-mt=""
+        data-paused={paused ? '' : undefined}
+        onPointerEnter={() => { setPointer(true); freeze(); }}
+        onPointerLeave={() => { setPointer(false); release(focus); }}
+        onFocus={() => { setFocus(true); freeze(); }}
+        onBlur={onBlur}
+        onKeyDown={onKeyDown}
+      >
+        {children(shown)}
+      </div>
+    </Context.Provider>
+  );
+}
+
+/** The table. Give it a caption through `caption`; the rows go inside `tbody`. */
+function Table({ caption, className, captionClassName, children }: { caption: string; className?: string; captionClassName?: string; children: ReactNode }) {
+  return (
+    <table className={className}>
+      <caption className={captionClassName}>{caption}</caption>
+      {children}
+    </table>
+  );
+}
+
+/** The header row. Put the `<th scope="col">` cells inside. */
+function Header({ className, children }: { className?: string; children: ReactNode }) {
+  return <thead><tr className={className}>{children}</tr></thead>;
+}
+
+/** One trade. A single tab stop for the tape: the active row, or the newest. Holding the pointer does not move it. */
+function Row({ row, selected, className, children }: { row: TapeRow; selected?: boolean; className?: string; children: ReactNode }) {
+  const { activeId, firstId, setActive } = useTape('Row');
+  const stop = activeId === null ? row.id === firstId : row.id === activeId;
+  return (
+    <tr
+      className={className}
+      data-tape-row={row.id}
+      aria-selected={selected === undefined ? undefined : selected}
+      tabIndex={stop ? 0 : -1}
+      onFocus={() => setActive(row.id)}
+    >
+      {children}
+    </tr>
+  );
+}
+
+/** The time as recorded, UTC. */
+function Time({ row, className }: { row: TapeRow; className?: string }) {
+  return <th scope="row" className={className} data-mt-numeric=""><time dateTime={row.t}>{row.time}</time></th>;
+}
+
+function Price({ row, className }: { row: TapeRow; className?: string }) {
+  return <td className={className} data-mt-numeric="">{row.price}</td>;
+}
+
+function Size({ row, className }: { row: TapeRow; className?: string }) {
+  return <td className={className} data-mt-numeric="">{row.size}</td>;
+}
+
+/** The side in words; tokens.css adds the mark so it never rests on colour alone. An unknown side has no colour. */
+function Side({ row, className, label }: { row: TapeRow; className?: string; label?: string }) {
+  return <td className={className} data-mt="" data-tape-side={row.side === 'unknown' ? undefined : row.side} title={row.side === 'unknown' ? 'The feed did not say which side was the aggressor' : undefined}>{label ?? TAPE_SIDE_LABEL[row.side]}</td>;
+}
+
+/** The polite live line: a summary of the tape on a timer. Render it once, outside the table. */
+function Summary({ className }: { className?: string }) {
+  const { summary } = useTape('Summary');
+  return <p className={className} role="status" aria-live="polite" aria-atomic="true">{summary}</p>;
+}
+
+/** What the tape is doing that the rows do not say: paused with N new waiting, and rows left out for breaking a rule. */
+function Status({ className, children }: { className?: string; children?: (state: { paused: boolean; waiting: number; issues: TapeIssue[] }) => ReactNode }) {
+  const { paused, waiting, issues } = useTape('Status');
+  if (children) return <div className={className}>{children({ paused, waiting, issues })}</div>;
+  const parts: string[] = [];
+  if (paused) parts.push(waiting > 0 ? `Paused. ${waiting} new ${waiting === 1 ? 'trade' : 'trades'} waiting.` : 'Paused while you read.');
+  if (issues.length) parts.push(`${issues.length} ${issues.length === 1 ? 'row' : 'rows'} left out: ${issues.slice(0, 3).map((i) => `row ${i.index + 1}, ${i.message}`).join('; ')}${issues.length > 3 ? '; …' : ''}.`);
+  if (!parts.length) return null;
+  return <p className={className} data-paused={paused ? '' : undefined}>{parts.join(' ')}</p>;
+}
+
+export { Root, Table, Header, Row, Time, Price, Size, Side, Summary, Status };

package/src/Toolbar.tsx

@@ -0,0 +1,6 @@
+import { Root, Button, Separator } from './ToolbarParts.js';
+
+// The parts live in ToolbarParts.js (a client module). The namespace object is built here, outside it, so a server
+// component can write `Toolbar.Root`: a property of an object exported from a client module is not reachable there.
+export * from './ToolbarParts.js';
+export const Toolbar = { Root, Button, Separator };