@matchstick-trading/primitives 0.0.10

package/src/core/ladder.ts

@@ -0,0 +1,156 @@
+/**
+ * The rules of the price ladder as plain functions. Prices and sizes arrive as exact decimal strings and are summed and
+ * grouped as scaled integers, never as floats; the only number made here is a bar's width, 0 to 1. A level that breaks a
+ * rule is reported and left out. A crossed book is reported and still drawn as given: nothing here repairs a book.
+ */
+
+export interface LadderLevelIn {
+  /** Exact decimal string, above zero. */
+  price: string;
+  /** Exact decimal string, above zero. */
+  size: string;
+}
+
+export interface LadderInput {
+  bids: readonly LadderLevelIn[];
+  asks: readonly LadderLevelIn[];
+  /** The grouping step, an exact decimal string above zero: `0.25` groups prices into quarters. Bids round down, asks round up, so grouping never crosses the spread. */
+  step: string;
+  /** Rows shown on each side, nearest the spread. Default 10. */
+  levels?: number;
+  /** The last trade price, for the divider row. */
+  last?: string;
+  /** Size traded at each price, for the traded column. A trade at or above the best ask is counted in the ask row's bucket, a lower one in the bid row's. */
+  traded?: readonly LadderLevelIn[];
+}
+
+export type LadderSide = 'bid' | 'ask';
+
+export interface LadderRow {
+  /** `side:price`, the row's identity (the price, not the position). */
+  id: string;
+  side: LadderSide;
+  /** The bucket's price, with as many decimal places as the step. */
+  price: string;
+  /** Total size in the bucket, with as many places as the most precise size given. */
+  size: string;
+  /** Size traded at this price, when any was. */
+  traded?: string;
+  /** Bar width: this row's size over the largest row shown, 0 to 1. */
+  fraction: number;
+  /** The best bid or the best ask. */
+  best: boolean;
+}
+
+export interface LadderIssue {
+  where: 'bids' | 'asks' | 'traded' | 'step' | 'last' | 'book';
+  /** Place in that list, when the problem is one entry. */
+  index?: number;
+  message: string;
+}
+
+export interface LadderBuilt {
+  /** Top to bottom: highest ask first, lowest ask last. */
+  asks: LadderRow[];
+  /** Top to bottom: highest bid first. */
+  bids: LadderRow[];
+  /** Asks then bids, the order a ladder is drawn. */
+  rows: LadderRow[];
+  /** The divider between asks and bids: the last price and the spread, each only when it can be said. */
+  last: { price?: string; spread?: string };
+  issues: LadderIssue[];
+}
+
+const POSITIVE = /^(\d+)(?:\.(\d+))?$/;
+
+interface Dec { units: bigint; places: number }
+
+function parse(value: unknown): Dec | null {
+  if (typeof value !== 'string') return null;
+  const m = POSITIVE.exec(value);
+  if (!m || !/[1-9]/.test(value)) return null;
+  const places = m[2]?.length ?? 0;
+  return { units: BigInt(m[1] + (m[2] ?? '')), places };
+}
+
+const rescale = (d: Dec, places: number): bigint => d.units * 10n ** BigInt(places - d.places);
+
+function show(units: bigint, places: number): string {
+  const digits = units.toString().padStart(places + 1, '0');
+  return places === 0 ? digits : `${digits.slice(0, -places)}.${digits.slice(-places)}`;
+}
+
+interface Good { index: number; price: Dec; size: Dec }
+
+function readLevels(list: readonly LadderLevelIn[] | undefined, where: 'bids' | 'asks' | 'traded', issues: LadderIssue[]): Good[] {
+  const out: Good[] = [];
+  (list ?? []).forEach((item, index) => {
+    const price = parse(item?.price);
+    const size = parse(item?.size);
+    if (!price || !size) { issues.push({ where, index, message: `${!price ? 'price' : 'size'} must be an exact decimal string above zero` }); return; }
+    out.push({ index, price, size });
+  });
+  return out;
+}
+
+/**
+ * Group the book into rows. Bids and asks are grouped by `step`, summed exactly, trimmed to `levels` rows a side, and
+ * given a bar width. Nothing is drawn for a level that breaks a rule; `issues` says which.
+ */
+export function buildLadder(input: LadderInput): LadderBuilt {
+  const issues: LadderIssue[] = [];
+  const empty: LadderBuilt = { asks: [], bids: [], rows: [], last: {}, issues };
+  const step = parse(input.step);
+  if (!step) { issues.push({ where: 'step', message: 'step must be an exact decimal string above zero' }); return empty; }
+  const bids = readLevels(input.bids, 'bids', issues);
+  const asks = readLevels(input.asks, 'asks', issues);
+  const traded = readLevels(input.traded, 'traded', issues);
+
+  const places = Math.max(step.places, ...bids.concat(asks, traded).map((g) => g.price.places));
+  const unit = rescale(step, places);
+  const sizePlaces = Math.max(0, ...bids.concat(asks, traded).map((g) => g.size.places));
+  const floor = (p: bigint) => (p / unit) * unit;
+  const ceil = (p: bigint) => ((p + unit - 1n) / unit) * unit;
+
+  const bucket = (list: Good[], round: (p: bigint) => bigint): Map<bigint, bigint> => {
+    const sums = new Map<bigint, bigint>();
+    for (const g of list) {
+      const key = round(rescale(g.price, places));
+      sums.set(key, (sums.get(key) ?? 0n) + rescale(g.size, sizePlaces));
+    }
+    return sums;
+  };
+  const descending = (a: bigint, b: bigint) => (a < b ? 1 : a > b ? -1 : 0);
+  const take = Math.max(1, Math.floor(input.levels ?? 10));
+  const bidBuckets = [...bucket(bids, floor)].sort((a, b) => descending(a[0], b[0])).slice(0, take);
+  const askBuckets = [...bucket(asks, ceil)].sort((a, b) => descending(b[0], a[0])).slice(0, take); // lowest first, nearest the spread
+
+  const bestBid = bids.length ? bids.reduce((m, g) => (rescale(g.price, places) > m ? rescale(g.price, places) : m), 0n) : null;
+  const bestAsk = asks.length ? asks.reduce((m, g) => { const p = rescale(g.price, places); return m === null || p < m ? p : m; }, null as bigint | null) : null;
+  if (bestBid !== null && bestAsk !== null && bestBid >= bestAsk) {
+    issues.push({ where: 'book', message: `crossed book: best bid ${show(bestBid, places)} is not below best ask ${show(bestAsk, places)}` });
+  }
+
+  // Traded size: at or above the best ask it belongs to an ask row, below it to a bid row.
+  const tradedUp = bucket(traded.filter((g) => bestAsk !== null && rescale(g.price, places) >= bestAsk), ceil);
+  const tradedDown = bucket(traded.filter((g) => bestAsk === null || rescale(g.price, places) < bestAsk), floor);
+
+  const largest = [...bidBuckets, ...askBuckets].reduce((m, [, s]) => (s > m ? s : m), 0n);
+  const bar = (s: bigint) => (largest === 0n ? 0 : Number((s * 10000n) / largest) / 10000);
+  const make = (side: LadderSide, [key, size]: [bigint, bigint], best: boolean, tradedMap: Map<bigint, bigint>): LadderRow => {
+    const price = show(key / 10n ** BigInt(places - step.places), step.places); // a bucket key is a whole number of steps, so this divides exactly
+    const t = tradedMap.get(key);
+    return { id: `${side}:${price}`, side, price, size: show(size, sizePlaces), traded: t === undefined ? undefined : show(t, sizePlaces), fraction: bar(size), best };
+  };
+  const askRows = askBuckets.map((b, i) => make('ask', b, i === 0, tradedUp)).reverse(); // drawn highest first
+  const bidRows = bidBuckets.map((b, i) => make('bid', b, i === 0, tradedDown));
+
+  const last: LadderBuilt['last'] = {};
+  if (input.last !== undefined) {
+    if (parse(input.last)) last.price = input.last;
+    else issues.push({ where: 'last', message: 'last must be an exact decimal string above zero' });
+  }
+  if (bestBid !== null && bestAsk !== null && bestAsk > bestBid) last.spread = show(bestAsk - bestBid, places);
+
+  return { asks: askRows, bids: bidRows, rows: [...askRows, ...bidRows], last, issues };
+}

package/src/core/panels.ts

@@ -0,0 +1,177 @@
+// Panels: a chart is one or more vertical bands, each with its own price scale, sharing one time axis. The bars (and the
+// volume under them) stay in the first band, "main". Other series are placed in a band by id, and move between bands by
+// relative destinations ("up", "down", "new panel above or below"), which is the single-pointer path WCAG 2.2 (2.5.7)
+// asks of any drag. The rules are plain functions so any framework layer, and a test, can use them.
+
+/** The id of the first band. It always exists, is always first, and holds the chart's own bars and volume. */
+export const MAIN_PANEL = 'main';
+
+export interface PanelSpec {
+  id: string;
+  /** What the band is called in lists and live-region text. */
+  label: string;
+  /** Share of the height. Default 1 for a panel and 3 for main. */
+  weight?: number;
+}
+
+export interface PanelLayout {
+  /** The bands from top to bottom. The first is always `main`. */
+  panels: readonly PanelSpec[];
+  /** Series id to panel id. A series with no entry, or a panel that is gone, is in `main`. */
+  placement: Readonly<Record<string, string>>;
+}
+
+export interface PanelBand {
+  id: string;
+  /** Top edge, from the top of the plot. */
+  top: number;
+  height: number;
+}
+
+/** Height kept under the bands for the time labels: the same as the chart frame's default `axisBottom`. */
+export const AXIS_BOTTOM = 18;
+
+const MIN_BAND = 40;
+const MAIN_WEIGHT = 3;
+
+const weightOf = (panel: PanelSpec) => (Number.isFinite(panel.weight) && (panel.weight as number) > 0 ? (panel.weight as number) : panel.id === MAIN_PANEL ? MAIN_WEIGHT : 1);
+
+/** A layout with only `main` (and the given bands below it), `main` forced to the front. */
+export function normalizeLayout(layout: PanelLayout): PanelLayout {
+  const seen = new Set<string>();
+  const rest: PanelSpec[] = [];
+  let main: PanelSpec = { id: MAIN_PANEL, label: 'Main' };
+  for (const panel of layout.panels ?? []) {
+    if (!panel || typeof panel.id !== 'string' || seen.has(panel.id)) continue;
+    seen.add(panel.id);
+    if (panel.id === MAIN_PANEL) main = { ...main, ...panel };
+    else rest.push(panel);
+  }
+  return { panels: [main, ...rest], placement: layout.placement ?? {} };
+}
+
+/** The panel a series is in: its placement when that panel exists, otherwise `main`. */
+export function panelOf(layout: PanelLayout, seriesId: string): string {
+  const wanted = layout.placement[seriesId];
+  return wanted !== undefined && layout.panels.some((p) => p.id === wanted) ? wanted : MAIN_PANEL;
+}
+
+/**
+ * Split `height` into bands by weight, top to bottom, with no gaps. A band is never shorter than 40 while the height
+ * allows it; with too little height the bands share what there is.
+ */
+export function panelBands(panels: readonly PanelSpec[], height: number): PanelBand[] {
+  const total = Number.isFinite(height) && height > 0 ? height : 1;
+  const weights = panels.map(weightOf);
+  const sum = weights.reduce((a, b) => a + b, 0) || 1;
+  const floor = Math.min(MIN_BAND, total / Math.max(1, panels.length));
+  let heights = weights.map((w) => Math.max(floor, (total * w) / sum));
+  // Taking the floor from some bands can overshoot; scale the bands that were above it back down.
+  const over = heights.reduce((a, b) => a + b, 0) - total;
+  if (over > 0.001) {
+    const spare = heights.reduce((a, h) => a + Math.max(0, h - floor), 0);
+    if (spare > 0) heights = heights.map((h) => h - (Math.max(0, h - floor) / spare) * over);
+  }
+  let top = 0;
+  return panels.map((p, i) => {
+    const h = i === panels.length - 1 ? Math.max(0, total - top) : Math.round(heights[i] * 100) / 100;
+    const band = { id: p.id, top: Math.round(top * 100) / 100, height: h };
+    top += h;
+    return band;
+  });
+}
+
+/** Where a series can go: an existing panel, or a new one beside the panel it is in. */
+export type MoveDestination =
+  | { kind: 'panel'; panelId: string }
+  | { kind: 'new'; side: 'above' | 'below'; beside: string };
+
+export interface MoveTarget {
+  destination: MoveDestination;
+  /** The words for a button, for example "Move up to Main" or "Move to a new panel below". */
+  label: string;
+}
+
+/**
+ * The destinations for one series, relative to where it is: the panel above, the panel below, a new panel above, a new
+ * panel below. A destination that would change nothing is left out (a lone series in a panel gains nothing from a new
+ * panel beside its own), and so is "new panel above" for `main`, which stays first.
+ */
+export function moveTargets(layout: PanelLayout, seriesId: string): MoveTarget[] {
+  const here = panelOf(layout, seriesId);
+  const at = layout.panels.findIndex((p) => p.id === here);
+  const out: MoveTarget[] = [];
+  const above = layout.panels[at - 1];
+  const below = layout.panels[at + 1];
+  if (above) out.push({ destination: { kind: 'panel', panelId: above.id }, label: `Move up to ${above.label}` });
+  if (below) out.push({ destination: { kind: 'panel', panelId: below.id }, label: `Move down to ${below.label}` });
+  const alone = here !== MAIN_PANEL && layout.panels.length > 0 && Object.keys(layout.placement).filter((id) => panelOf(layout, id) === here).length <= 1;
+  if (here !== MAIN_PANEL && !alone) out.push({ destination: { kind: 'new', side: 'above', beside: here }, label: 'Move to a new panel above' });
+  if (!alone) out.push({ destination: { kind: 'new', side: 'below', beside: here }, label: 'Move to a new panel below' });
+  return out;
+}
+
+const nextPanelId = (panels: readonly PanelSpec[]): { id: string; label: string } => {
+  let n = panels.length;
+  const ids = new Set(panels.map((p) => p.id));
+  while (ids.has(`panel-${n}`)) n++;
+  return { id: `panel-${n}`, label: `Panel ${n}` };
+};
+
+/**
+ * Move a series. Returns the same layout object when nothing changes. A panel left with no series is removed (never
+ * `main`). The result is a new layout: the arguments are not changed.
+ */
+export function moveSeries(layout: PanelLayout, seriesId: string, destination: MoveDestination): PanelLayout {
+  const here = panelOf(layout, seriesId);
+  let panels = [...layout.panels];
+  let target: string;
+  if (destination.kind === 'panel') {
+    if (!panels.some((p) => p.id === destination.panelId) || destination.panelId === here) return layout;
+    target = destination.panelId;
+  } else {
+    const beside = panels.findIndex((p) => p.id === destination.beside);
+    if (beside < 0) return layout;
+    if (destination.side === 'above' && panels[beside].id === MAIN_PANEL) return layout; // main stays first
+    const made = nextPanelId(panels);
+    panels.splice(destination.side === 'above' ? beside : beside + 1, 0, { id: made.id, label: made.label });
+    target = made.id;
+  }
+  const placement = { ...layout.placement, [seriesId]: target };
+  const used = new Set(Object.keys(placement).map((id) => panelOf({ panels, placement }, id)));
+  panels = panels.filter((p) => p.id === MAIN_PANEL || used.has(p.id) || p.id === target);
+  return { panels, placement };
+}
+
+/** The words for a live region after a move, for example "Moved RSI to Panel 2." */
+export function describeMove(label: string, panelLabel: string): string {
+  return `Moved ${label} to ${panelLabel}.`;
+}
+
+/** A series as `reconcileLayout` reads it: its id and the panel it asks to start in. */
+export interface PanelSeriesRequest { id: string; panel?: string }
+
+/**
+ * Bring an uncontrolled layout in step with a changed list of series, keeping every placement a person already made.
+ * A series that is new (not in `seen`) starts in the panel it names, which is created below `main` when it does not
+ * exist (labelled from `named`, else its id). A series that is gone loses its placement, and a panel left with no
+ * series is removed. Returns the same layout when nothing changes.
+ */
+export function reconcileLayout(layout: PanelLayout, series: readonly PanelSeriesRequest[], seen: readonly string[], named: readonly PanelSpec[] = []): PanelLayout {
+  const now = new Set(series.map((s) => s.id));
+  const before = new Set(seen);
+  let panels = [...layout.panels];
+  const placement: Record<string, string> = { ...layout.placement };
+  let changed = false;
+  for (const id of seen) if (!now.has(id) && id in placement) { delete placement[id]; changed = true; }
+  for (const s of series) {
+    if (before.has(s.id) || !s.panel || s.panel === MAIN_PANEL) continue;
+    if (!panels.some((p) => p.id === s.panel)) panels.push(named.find((n) => n.id === s.panel) ?? { id: s.panel, label: s.panel });
+    placement[s.id] = s.panel;
+    changed = true;
+  }
+  const used = new Set(Object.keys(placement).map((id) => placement[id]));
+  const kept = panels.filter((p) => p.id === MAIN_PANEL || used.has(p.id));
+  if (kept.length !== panels.length) { panels = kept; changed = true; }
+  return changed ? { panels, placement } : layout;
+}

package/src/core/receipt-rules.ts

@@ -0,0 +1,45 @@
+/**
+ * The rules of the evidence receipt as plain functions. Digests and sizes are strings and are
+ * printed as given.
+ */
+export interface ReceiptData {
+  dataset: string;
+  symbol: string;
+  synthetic: boolean;
+  a: string;
+  b: string;
+  eventsBetween: number;
+  sourceDigest: string;
+  stateDigestA: string;
+  stateDigestB: string;
+  resultHash: string;
+  engineVersion: string;
+  levelsDiffer: number;
+  /** Whether replaying from the start gave the same two states and the same result hash. */
+  recomputeMatch: boolean;
+  /** The line that must travel with a copy when the data is not synthetic. */
+  shareNote?: string;
+}
+
+export type ReceiptVerdict = 'match' | 'mismatch';
+export const receiptVerdict = (receipt: Pick<ReceiptData, 'recomputeMatch'>): ReceiptVerdict => (receipt.recomputeMatch ? 'match' : 'mismatch');
+
+export type ReceiptHashOf = 'source' | 'a' | 'b' | 'result';
+export function receiptHash(receipt: ReceiptData, of: ReceiptHashOf): string {
+  return of === 'source' ? receipt.sourceDigest : of === 'a' ? receipt.stateDigestA : of === 'b' ? receipt.stateDigestB : receipt.resultHash;
+}
+
+interface KeyLike { key: string; ctrlKey: boolean; metaKey: boolean; altKey: boolean }
+
+/**
+ * Enter or `y` copies the result hash. Enter on a button or link is that control's own and is left alone; `y` is
+ * ignored while typing in a field.
+ */
+export function resolveReceiptKey(event: KeyLike, target: { tagName: string; isContentEditable?: boolean }): 'copy-hash' | null {
+  if (event.ctrlKey || event.metaKey || event.altKey) return null;
+  const tag = target.tagName.toLowerCase();
+  if (tag === 'input' || tag === 'textarea' || tag === 'select' || target.isContentEditable) return null;
+  if (event.key === 'y') return 'copy-hash';
+  if (event.key === 'Enter' && tag !== 'button' && tag !== 'a') return 'copy-hash';
+  return null;
+}

package/src/core/scrubber-gesture.ts

@@ -0,0 +1,102 @@
+/**
+ * The scrub gesture as plain data in, plain data out. Everything here works on a fraction of the
+ * track, 0 to 1, and knows nothing about time, sequences or events: the host turns a committed fraction into a
+ * place in its session. That keeps the rules testable without a DOM and keeps the Scrubber usable on any ruler.
+ */
+
+/** Clamp a track fraction to [0, 1]; a value that is not a finite number becomes 0. */
+export function clampFraction(value: number): number {
+  if (!Number.isFinite(value)) return 0;
+  return value < 0 ? 0 : value > 1 ? 1 : value;
+}
+
+export type ScrubGestureEvent =
+  | { type: 'down'; fraction: number }
+  | { type: 'move'; fraction: number }
+  /**
+   * `fraction` is where the release itself landed: pointer input coalesces, so the release can be measurably ahead
+   * of the last move. When it is left out the last previewed fraction is used. `loading` is whether the host is
+   * already busy with another navigation at the moment of release, passed in as data so the decision lives here.
+   */
+  | { type: 'up'; fraction?: number; loading?: boolean }
+  | { type: 'cancel' };
+
+export interface ScrubGestureResult {
+  /** The next preview fraction; null when no drag is in progress. */
+  dragFraction: number | null;
+  /** Non-null exactly once per gesture: the fraction to commit when the pointer is released. */
+  commit: number | null;
+  begin: boolean;
+  end: boolean;
+}
+
+const IDLE: Omit<ScrubGestureResult, 'dragFraction'> = { commit: null, begin: false, end: false };
+
+/**
+ * Moving only ever changes the preview; only a release, with a drag in progress, commits, and it commits once.
+ * A release while the host is loading ends the gesture without committing, so two navigations are never in
+ * flight at once. A cancelled gesture (the pointer left the window) never commits.
+ */
+export function reduceScrubGesture(event: ScrubGestureEvent, dragFraction: number | null): ScrubGestureResult {
+  switch (event.type) {
+    case 'down':
+      return { dragFraction: clampFraction(event.fraction), commit: null, begin: true, end: false };
+    case 'move':
+      return dragFraction === null ? { dragFraction, ...IDLE } : { dragFraction: clampFraction(event.fraction), ...IDLE };
+    case 'up':
+      if (dragFraction === null) return { dragFraction: null, ...IDLE };
+      if (event.loading) return { dragFraction: null, commit: null, begin: false, end: true };
+      return { dragFraction: null, commit: clampFraction(event.fraction ?? dragFraction), begin: false, end: true };
+    case 'cancel':
+      return dragFraction === null ? { dragFraction: null, ...IDLE } : { dragFraction: null, commit: null, begin: false, end: true };
+  }
+}
+
+/** The two pointer fields a scrub gate reads, named so the gates are testable without a DOM event. */
+export interface ScrubPointer {
+  /** 0 is the primary button (left, or a pen or touch contact). */
+  button: number;
+  /** False for any additional simultaneous contact in a multi-touch gesture. */
+  isPrimary: boolean;
+}
+
+/** Whether a pointer-down may start a scrub. A right-click, middle-click or second finger is left to the browser. */
+export function isPrimaryScrubPointer(event: ScrubPointer): boolean {
+  return event.button === 0 && event.isPrimary;
+}
+
+/** Whether a move, up or cancel belongs to the pointer that began the drag now in progress (a second contact cannot hijack it). */
+export function isActiveScrubPointer(pointerId: number, activePointerId: number | null): boolean {
+  return activePointerId !== null && pointerId === activePointerId;
+}
+
+/** Where a pointer sits along a track, as a fraction. A track with no width reads as 0. */
+export function fractionFromPointer(clientX: number, left: number, width: number): number {
+  if (!(width > 0)) return 0;
+  return clampFraction((clientX - left) / width);
+}
+
+export type ScrubKeyAction = { type: 'step'; direction: -1 | 1 } | { type: 'jump'; fraction: number };
+
+/**
+ * Arrow keys step one event, which only the host can define, so they resolve to a direction. Home and End jump to
+ * the ends; PageUp and PageDown move 10% of the track. Any other key is left alone (null).
+ */
+export function resolveScrubKey(key: string, currentFraction: number): ScrubKeyAction | null {
+  switch (key) {
+    case 'ArrowLeft':
+      return { type: 'step', direction: -1 };
+    case 'ArrowRight':
+      return { type: 'step', direction: 1 };
+    case 'Home':
+      return { type: 'jump', fraction: 0 };
+    case 'End':
+      return { type: 'jump', fraction: 1 };
+    case 'PageUp':
+      return { type: 'jump', fraction: clampFraction(currentFraction + 0.1) };
+    case 'PageDown':
+      return { type: 'jump', fraction: clampFraction(currentFraction - 0.1) };
+    default:
+      return null;
+  }
+}

package/src/core/selection.ts

@@ -0,0 +1,41 @@
+// One selection for a chart: a drawing, the bar series or a study, never more than one. The rules are plain functions
+// so any framework layer (and a test) can use them.
+
+/** What is selected on a chart, or null for nothing. */
+export type ChartSelection = { kind: 'drawing' | 'series' | 'study'; id: string } | null;
+
+/** True when two selections point at the same thing. */
+export function sameSelection(a: ChartSelection, b: ChartSelection): boolean {
+  return a === b || (a !== null && b !== null && a.kind === b.kind && a.id === b.id);
+}
+
+/**
+ * A tap on clear chart (no drawing, no study under it). With something selected, it only puts the selection away. With
+ * nothing selected it selects the series when one is mounted (`seriesId`), and otherwise changes nothing. Returns the
+ * same value when nothing changes.
+ */
+export function selectionAfterClearTap(selection: ChartSelection, seriesId: string | null): ChartSelection {
+  if (selection !== null) return null;
+  return seriesId !== null ? { kind: 'series', id: seriesId } : selection;
+}
+
+/** A tap on something selectable (a study line) selects it, whatever was selected before. */
+export function selectionAfterTap(selection: ChartSelection, hit: ChartSelection, seriesId: string | null): ChartSelection {
+  if (hit === null) return selectionAfterClearTap(selection, seriesId);
+  return sameSelection(selection, hit) ? selection : hit;
+}
+
+/** Escape clears whatever is selected. */
+export function selectionAfterEscape(selection: ChartSelection): ChartSelection {
+  return selection === null ? selection : null;
+}
+
+/** The names a selection can be described with, per kind and id. A missing name falls back to the id. */
+export type SelectionNames = { [K in 'drawing' | 'series' | 'study']?: Readonly<Record<string, string>> };
+
+/** The words for a live region: what is selected now, or that nothing is. */
+export function describeSelection(selection: ChartSelection, names: SelectionNames = {}): string {
+  if (selection === null) return 'Selection cleared.';
+  const name = names[selection.kind]?.[selection.id] ?? selection.id;
+  return `Selected ${selection.kind}: ${name}.`;
+}