@matchstick-trading/primitives 0.0.10

package/dist/core/index.d.ts

@@ -0,0 +1,41 @@
+export { numericWidthValue, primitiveAttributes } from './attributes.js';
+export type { Change, CursorMark, DiffStatus, PrimitiveAttributes, PrimitiveState, Quality, Side } from './attributes.js';
+export { isRowShown, LADDER_ROW_ATTRIBUTE, nextLadderRow, resolveLadderKey } from './ladder-keys.js';
+export type { LadderKeyAction, LadderKeyInput } from './ladder-keys.js';
+export { clampFraction, fractionFromPointer, isActiveScrubPointer, isPrimaryScrubPointer, reduceScrubGesture, resolveScrubKey } from './scrubber-gesture.js';
+export type { ScrubGestureEvent, ScrubGestureResult, ScrubKeyAction, ScrubPointer } from './scrubber-gesture.js';
+export { DEPTH_HEIGHT, DEPTH_WIDTH, depthGeometry, depthLevelId, nextDepthIndex, resolveDepthKey } from './depth-profile.js';
+export type { DepthGeometry, DepthKeyAction, DepthLevel } from './depth-profile.js';
+export { DIFF_CHANGE_LABEL, compareExact, diffRowId, holdDiffOrder, nextDiffIndex, nextDiffSort, resolveDiffKey, signedDelta, sortDiffRows } from './diff-table.js';
+export type { DiffChange, DiffKeyAction, DiffMove, DiffSort, DiffTableRow } from './diff-table.js';
+export { TAPE_SIDE_LABEL, holdTape, newestFirst, nextTapeIndex, readTape, resolveTapeKey, tapeSummary, tapeTime } from './tape.js';
+export type { TapeIssue, TapeKeyAction, TapeMove, TapeRead, TapeRow, TapeSide, TapeTrade } from './tape.js';
+export { buildLadder } from './ladder.js';
+export type { LadderBuilt, LadderInput, LadderIssue, LadderLevelIn, LadderRow, LadderSide } from './ladder.js';
+export { receiptHash, receiptVerdict, resolveReceiptKey } from './receipt-rules.js';
+export type { ReceiptData, ReceiptHashOf, ReceiptVerdict } from './receipt-rules.js';
+export { buildSymbolIndex, nextSymbolIndex, normalizeSymbolText, resolveSymbolKey, searchSymbols } from './symbol-search.js';
+export type { Instrument, MatchHow, MatchedOn, SearchOptions, SymbolIndex, SymbolKeyAction, SymbolMatch } from './symbol-search.js';
+export { barInterval, chartFrame, clampPriceRange, dataPriceSpan, growViewport, indexOfTime, lastBars, panPriceRange, panViewport, priceTicks, resolveChartKey, tickDecimals, timeOfIndex, zoomPriceRange, zoomViewport } from './chart-scale.js';
+export type { CandleBar, ChartFrame, ChartFrameOptions, ChartInclude, PriceSpan, ChartKeyAction, ChartSize, ChartViewport } from './chart-scale.js';
+export { INITIAL_CHART_GESTURE, isChartGestureActive, reduceChartGesture } from './chart-gesture.js';
+export type { ChartGestureEvent, ChartGestureResult, ChartGestureState, ChartGestureView, ChartPoint } from './chart-gesture.js';
+export { atr, bollinger, ema, rsi, sma, sourcePrice, studyRange, visibleIndexes, vwap, wma } from './studies.js';
+export type { BollingerBands, Series, StudySource, VwapBand, VwapOptions, VwapResult } from './studies.js';
+export { indexRangeOfTime, volumeProfile } from './volume-profile.js';
+export type { ProfileRow, VolumeProfileOptions, VolumeProfileResult } from './volume-profile.js';
+export { ATTACH_LABELS, ATTACH_MODES, DRAWING_TOOLS, DRAWING_TOOL_LABELS, FIB_RATIOS, anchorCount, attachOf, barTime, barsFromFirst, barsFromLast, timeOfBarFromLast, describeAnchor, describeDrawing, drawingGeometry, drawingPriceRanges, editDrawing, hitTest, moveAnchor, moveDrawing, nextDrawingId, nudgeAmount, resolveDrawingKey, snapToBar } from './drawings.js';
+export type { AttachMode, Drawing, DrawingAnchor, DrawingGeometry, DrawingHit, DrawingKeyAction, DrawingTool, SnapMode } from './drawings.js';
+export { describeBarsCsv, parseBarsCsv } from './csv-bars.js';
+export type { CsvBarsError, CsvBarsNote, CsvBarsOptions, CsvBarsResult, CsvExtraColumn } from './csv-bars.js';
+export { formatBarTime, heikinAshi } from './candles.js';
+export { barField, barNote, fromPriceField, fromTimeField, parseBarField, toTimeField } from './drawing-fields.js';
+export { describeSelection, sameSelection, selectionAfterClearTap, selectionAfterEscape, selectionAfterTap } from './selection.js';
+export type { ChartSelection, SelectionNames } from './selection.js';
+export { AXIS_BOTTOM, MAIN_PANEL, describeMove, moveSeries, moveTargets, normalizeLayout, panelBands, panelOf, reconcileLayout } from './panels.js';
+export type { MoveDestination, MoveTarget, PanelBand, PanelLayout, PanelSeriesRequest, PanelSpec } from './panels.js';
+export { POINT_KINDS, alignSeries, duplicateIds, pointsFromValues, report, resolveSeries, seriesSetSchema, validateSeriesSet } from './series.js';
+export type { AlignMode, AlignOptions, AlignedSeries, AlignedState, DataSeries, FindingKind, PointKind, ResolvedSeries, SeriesCalendar, SeriesFinding, SeriesInput, SeriesIssue, SeriesPoint, SeriesSet, SeriesValidation } from './series.js';
+export { csvAdapter, toSeriesSet } from './adapter.js';
+export type { AdapterIssue, AdapterResult, CsvAdapterOptions, DataAdapter } from './adapter.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/core/index.js

@@ -0,0 +1,23 @@
+// The plain-TypeScript core of the primitives: geometry, state rules, studies and key maps with no React and no
+// other import. A framework layer (the React parts beside this folder) imports from here; so can any other code.
+export { numericWidthValue, primitiveAttributes } from './attributes.js';
+export { isRowShown, LADDER_ROW_ATTRIBUTE, nextLadderRow, resolveLadderKey } from './ladder-keys.js';
+export { clampFraction, fractionFromPointer, isActiveScrubPointer, isPrimaryScrubPointer, reduceScrubGesture, resolveScrubKey } from './scrubber-gesture.js';
+export { DEPTH_HEIGHT, DEPTH_WIDTH, depthGeometry, depthLevelId, nextDepthIndex, resolveDepthKey } from './depth-profile.js';
+export { DIFF_CHANGE_LABEL, compareExact, diffRowId, holdDiffOrder, nextDiffIndex, nextDiffSort, resolveDiffKey, signedDelta, sortDiffRows } from './diff-table.js';
+export { TAPE_SIDE_LABEL, holdTape, newestFirst, nextTapeIndex, readTape, resolveTapeKey, tapeSummary, tapeTime } from './tape.js';
+export { buildLadder } from './ladder.js';
+export { receiptHash, receiptVerdict, resolveReceiptKey } from './receipt-rules.js';
+export { buildSymbolIndex, nextSymbolIndex, normalizeSymbolText, resolveSymbolKey, searchSymbols } from './symbol-search.js';
+export { barInterval, chartFrame, clampPriceRange, dataPriceSpan, growViewport, indexOfTime, lastBars, panPriceRange, panViewport, priceTicks, resolveChartKey, tickDecimals, timeOfIndex, zoomPriceRange, zoomViewport } from './chart-scale.js';
+export { INITIAL_CHART_GESTURE, isChartGestureActive, reduceChartGesture } from './chart-gesture.js';
+export { atr, bollinger, ema, rsi, sma, sourcePrice, studyRange, visibleIndexes, vwap, wma } from './studies.js';
+export { indexRangeOfTime, volumeProfile } from './volume-profile.js';
+export { ATTACH_LABELS, ATTACH_MODES, DRAWING_TOOLS, DRAWING_TOOL_LABELS, FIB_RATIOS, anchorCount, attachOf, barTime, barsFromFirst, barsFromLast, timeOfBarFromLast, describeAnchor, describeDrawing, drawingGeometry, drawingPriceRanges, editDrawing, hitTest, moveAnchor, moveDrawing, nextDrawingId, nudgeAmount, resolveDrawingKey, snapToBar } from './drawings.js';
+export { describeBarsCsv, parseBarsCsv } from './csv-bars.js';
+export { formatBarTime, heikinAshi } from './candles.js';
+export { barField, barNote, fromPriceField, fromTimeField, parseBarField, toTimeField } from './drawing-fields.js';
+export { describeSelection, sameSelection, selectionAfterClearTap, selectionAfterEscape, selectionAfterTap } from './selection.js';
+export { AXIS_BOTTOM, MAIN_PANEL, describeMove, moveSeries, moveTargets, normalizeLayout, panelBands, panelOf, reconcileLayout } from './panels.js';
+export { POINT_KINDS, alignSeries, duplicateIds, pointsFromValues, report, resolveSeries, seriesSetSchema, validateSeriesSet } from './series.js';
+export { csvAdapter, toSeriesSet } from './adapter.js';

package/dist/core/ladder-keys.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Ladder keyboard contract. Read-only: no key places or changes an order.
+ *
+ * | Key           | Action                                                         |
+ * |---------------|----------------------------------------------------------------|
+ * | ArrowDown     | focus the next row down                                        |
+ * | ArrowUp       | focus the next row up                                          |
+ * | Home          | focus the best bid                                             |
+ * | End           | focus the best ask                                             |
+ * | Enter / Space | seek to when this level last changed (when the host supplies it) |
+ *
+ * One row is the tab stop (roving tabindex), so Tab leaves the ladder in one press. Home and End are also the
+ * global transport "start" and "end" keys; inside the ladder they mean best bid and best ask, and the ladder
+ * stops them there.
+ */
+export type LadderKeyAction = 'next' | 'previous' | 'best-bid' | 'best-ask';
+/** The fields of a keyboard event the contract reads; a DOM or React KeyboardEvent fits. */
+export interface LadderKeyInput {
+    key: string;
+    altKey: boolean;
+    ctrlKey: boolean;
+    metaKey: boolean;
+    shiftKey: boolean;
+}
+export declare function resolveLadderKey(event: LadderKeyInput): LadderKeyAction | null;
+/** Marks a row for the contract. `best` rows are what Home and End jump to. */
+export declare const LADDER_ROW_ATTRIBUTE = "data-ladder-row";
+/**
+ * On screen: it has a box and no closed `<details>` above it. Chromium still reports boxes for the contents of a
+ * closed disclosure, so the box test alone is not enough.
+ */
+export declare function isRowShown(row: HTMLElement): boolean;
+/** The row to focus, or null when the key does nothing here. `rows` are in screen order, top to bottom. */
+export declare function nextLadderRow(rows: readonly HTMLElement[], current: HTMLElement | null, action: LadderKeyAction): HTMLElement | null;
+//# sourceMappingURL=ladder-keys.d.ts.map

package/dist/core/ladder-keys.js

@@ -0,0 +1,43 @@
+export function resolveLadderKey(event) {
+    if (event.altKey || event.ctrlKey || event.metaKey || event.shiftKey)
+        return null;
+    switch (event.key) {
+        case 'ArrowDown':
+            return 'next';
+        case 'ArrowUp':
+            return 'previous';
+        case 'Home':
+            return 'best-bid';
+        case 'End':
+            return 'best-ask';
+        default:
+            return null;
+    }
+}
+/** Marks a row for the contract. `best` rows are what Home and End jump to. */
+export const LADDER_ROW_ATTRIBUTE = 'data-ladder-row';
+/**
+ * On screen: it has a box and no closed `<details>` above it. Chromium still reports boxes for the contents of a
+ * closed disclosure, so the box test alone is not enough.
+ */
+export function isRowShown(row) {
+    for (let el = row.parentElement; el; el = el.parentElement) {
+        if (el instanceof HTMLDetailsElement && !el.open)
+            return false;
+    }
+    return row.getClientRects().length > 0;
+}
+/** The row to focus, or null when the key does nothing here. `rows` are in screen order, top to bottom. */
+export function nextLadderRow(rows, current, action) {
+    if (!rows.length)
+        return null;
+    if (action === 'best-bid')
+        return rows.find((row) => row.dataset.best === 'bid') ?? null;
+    if (action === 'best-ask')
+        return rows.find((row) => row.dataset.best === 'ask') ?? null;
+    const at = current ? rows.indexOf(current) : -1;
+    if (at < 0)
+        return rows[0] ?? null;
+    const to = action === 'next' ? at + 1 : at - 1;
+    return rows[to] ?? null; // stops at the ends; never wraps
+}

package/dist/core/ladder.d.ts

@@ -0,0 +1,65 @@
+/**
+ * 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[];
+}
+/**
+ * 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 declare function buildLadder(input: LadderInput): LadderBuilt;
+//# sourceMappingURL=ladder.d.ts.map

package/dist/core/ladder.js

@@ -0,0 +1,93 @@
+/**
+ * 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.
+ */
+const POSITIVE = /^(\d+)(?:\.(\d+))?$/;
+function parse(value) {
+    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, places) => d.units * 10n ** BigInt(places - d.places);
+function show(units, places) {
+    const digits = units.toString().padStart(places + 1, '0');
+    return places === 0 ? digits : `${digits.slice(0, -places)}.${digits.slice(-places)}`;
+}
+function readLevels(list, where, issues) {
+    const out = [];
+    (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) {
+    const issues = [];
+    const empty = { 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) => (p / unit) * unit;
+    const ceil = (p) => ((p + unit - 1n) / unit) * unit;
+    const bucket = (list, round) => {
+        const sums = new Map();
+        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, b) => (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) : 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) => (largest === 0n ? 0 : Number((s * 10000n) / largest) / 10000);
+    const make = (side, [key, size], best, tradedMap) => {
+        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 = {};
+    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/dist/core/panels.d.ts

@@ -0,0 +1,72 @@
+/** The id of the first band. It always exists, is always first, and holds the chart's own bars and volume. */
+export declare 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 declare const AXIS_BOTTOM = 18;
+/** A layout with only `main` (and the given bands below it), `main` forced to the front. */
+export declare function normalizeLayout(layout: PanelLayout): PanelLayout;
+/** The panel a series is in: its placement when that panel exists, otherwise `main`. */
+export declare function panelOf(layout: PanelLayout, seriesId: string): string;
+/**
+ * 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 declare function panelBands(panels: readonly PanelSpec[], height: number): PanelBand[];
+/** 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 declare function moveTargets(layout: PanelLayout, seriesId: string): MoveTarget[];
+/**
+ * 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 declare function moveSeries(layout: PanelLayout, seriesId: string, destination: MoveDestination): PanelLayout;
+/** The words for a live region after a move, for example "Moved RSI to Panel 2." */
+export declare function describeMove(label: string, panelLabel: string): string;
+/** 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 declare function reconcileLayout(layout: PanelLayout, series: readonly PanelSeriesRequest[], seen: readonly string[], named?: readonly PanelSpec[]): PanelLayout;
+//# sourceMappingURL=panels.d.ts.map

package/dist/core/panels.js

@@ -0,0 +1,151 @@
+// 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';
+/** 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) => (Number.isFinite(panel.weight) && panel.weight > 0 ? panel.weight : 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) {
+    const seen = new Set();
+    const rest = [];
+    let main = { 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, seriesId) {
+    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, height) {
+    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;
+    });
+}
+/**
+ * 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, seriesId) {
+    const here = panelOf(layout, seriesId);
+    const at = layout.panels.findIndex((p) => p.id === here);
+    const out = [];
+    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) => {
+    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, seriesId, destination) {
+    const here = panelOf(layout, seriesId);
+    let panels = [...layout.panels];
+    let target;
+    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, panelLabel) {
+    return `Moved ${label} to ${panelLabel}.`;
+}
+/**
+ * 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, series, seen, named = []) {
+    const now = new Set(series.map((s) => s.id));
+    const before = new Set(seen);
+    let panels = [...layout.panels];
+    const placement = { ...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/dist/core/receipt-rules.d.ts

@@ -0,0 +1,42 @@
+/**
+ * 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 declare const receiptVerdict: (receipt: Pick<ReceiptData, "recomputeMatch">) => ReceiptVerdict;
+export type ReceiptHashOf = 'source' | 'a' | 'b' | 'result';
+export declare function receiptHash(receipt: ReceiptData, of: ReceiptHashOf): string;
+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 declare function resolveReceiptKey(event: KeyLike, target: {
+    tagName: string;
+    isContentEditable?: boolean;
+}): 'copy-hash' | null;
+export {};
+//# sourceMappingURL=receipt-rules.d.ts.map

package/dist/core/receipt-rules.js

@@ -0,0 +1,20 @@
+export const receiptVerdict = (receipt) => (receipt.recomputeMatch ? 'match' : 'mismatch');
+export function receiptHash(receipt, of) {
+    return of === 'source' ? receipt.sourceDigest : of === 'a' ? receipt.stateDigestA : of === 'b' ? receipt.stateDigestB : receipt.resultHash;
+}
+/**
+ * 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, target) {
+    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;
+}