@stocksharp/trading-controls 1.1.1 → 1.3.0

package/src/option-desk-widget.ts

@@ -0,0 +1,422 @@
+// Option desk — multi-instance.
+//
+// One expiry of a chain, strike by strike: the call's side on the left, the put's mirrored on
+// the right, and the strike between them. Every figure a trader compares across the strip -
+// volume, open interest, volatility - carries a bar as well as a number, because a chain is
+// read by shape first and by value second.
+//
+// Two scales, and the difference matters. Volume and open interest are scaled per side, since
+// calls and puts trade in different sizes and comparing a call's volume against the busiest put
+// says nothing. Volatility is scaled across BOTH sides at once - a skew is exactly the
+// comparison between them, and two independent scales would flatten it.
+//
+// Greeks arrive one of two ways. A host that computes them sends them and the desk shows what
+// it was given; a host that sends volatility instead has them computed here, from the same
+// Black-Scholes the desktop uses. Neither is a fallback for the other going wrong - they are
+// two shapes of host, and which one a row came from is not the desk's business.
+import { formatPrice, formatQty } from './formatters.js';
+import { makeElement, makeIconButton, makePanelId, makePanelRoot } from './dom.js';
+import { ControlTypes } from './control-types.js';
+import { makeGridMenu } from './grid-menu.js';
+import { TradingHost, assertHost } from './trading-host.js';
+import { OptionTypes, greeks as computeGreeks, type Greeks } from './black-scholes.js';
+import { DataGrid, GridColumn } from '@stocksharp/grids/source/data-grid';
+
+/// One contract's side of a strike.
+export interface OptionSide {
+    symbol?: string;
+    bid?: number | null;
+    ask?: number | null;
+    last?: number | null;
+    /// What the venue says it is worth, when it says.
+    theoretical?: number | null;
+    volume?: number | null;
+    openInterest?: number | null;
+    /// Implied volatility as a fraction, by the price it was solved from.
+    ivBid?: number | null;
+    ivAsk?: number | null;
+    ivLast?: number | null;
+    historicalVolatility?: number | null;
+    /// Sent by a host that computes them. Left out, they are computed from `iv` below.
+    greeks?: Greeks;
+}
+
+/// One strike, both sides of it.
+export interface OptionStrike {
+    strike: number;
+    call: OptionSide;
+    put: OptionSide;
+}
+
+/// What the chain is priced against. Without it the desk still shows quotes, and shows no
+/// greeks: they are not a property of the option alone.
+export interface OptionChainContext {
+    /// The underlying's price.
+    assetPrice?: number | null;
+    /// Years to expiry.
+    timeToExpiry?: number | null;
+    riskFree?: number;
+    dividend?: number;
+}
+
+export interface OptionDeskDeps {
+    host: TradingHost;
+}
+
+interface DeskRow extends OptionStrike {
+    /// Bar scales, resolved once per refresh over the whole chain rather than per row.
+    maxCallVolume: number;
+    maxPutVolume: number;
+    maxCallOpenInterest: number;
+    maxPutOpenInterest: number;
+    maxVolatility: number;
+    /// What the option is worth if exercised now. Zero for a strike out of the money.
+    callIntrinsic: number;
+    putIntrinsic: number;
+}
+
+export class OptionDeskWidget {
+    static TYPE = ControlTypes.OptionDesk;
+
+    rootEl: HTMLElement;
+    el: HTMLElement | null;
+    // `//` rather than `///` from here down — see the note in positions-widget.
+    _host: TradingHost;
+    _closeBtn: HTMLElement | null;
+    _exportBtn: HTMLElement | null;
+    _rows: DeskRow[];
+    _context: OptionChainContext;
+    _places: Record<keyof Greeks, number>;
+    _grid: DataGrid<DeskRow> | null;
+
+    static create(hostEl: HTMLElement, state: Record<string, unknown>, deps: OptionDeskDeps): OptionDeskWidget {
+        const host = assertHost(deps?.host, 'OptionDeskWidget');
+        const root = OptionDeskWidget._buildRoot(host);
+        root.id = makePanelId(OptionDeskWidget.TYPE);
+        hostEl.appendChild(root);
+        return new OptionDeskWidget(root, state || {}, deps);
+    }
+
+    static _buildRoot(host: TradingHost): HTMLElement {
+        const title = host.t('OptionDesk');
+        return makePanelRoot('option-desk-panel', title, [
+            makeElement('div', 'panel-header', {}, [
+                makeElement('span', '', {}, [title]),
+                makeIconButton('bt-icon-btn bt-icon-cancel panel-close-btn', host.t('ClosePanel'), 'bi-x', { type: 'button' }),
+            ]),
+            makeElement('div', 'panel-body panel-body-with-rail', {}, [
+                makeElement('div', 'panel-body-content', {}, [
+                    makeElement('table', 'terminal-table option-desk-table', { role: 'table', 'aria-label': host.t('OptionChain') }, [
+                        makeElement('thead', '', {}, []),
+                        makeElement('tbody', 'option-desk-body', {}, []),
+                    ]),
+                ]),
+                makeElement('div', 'panel-rail', { role: 'toolbar', 'aria-label': host.t('OptionDeskActions') }, [
+                    makeIconButton('bt-icon-btn panel-export-btn', host.t('ExportToExcel'), 'bi-file-earmark-spreadsheet', {}),
+                ]),
+            ]),
+        ]);
+    }
+
+    constructor(rootEl: HTMLElement, _state: Record<string, unknown>, deps: OptionDeskDeps) {
+        this._host = assertHost(deps?.host, 'OptionDeskWidget');
+
+        this.rootEl = rootEl;
+        this.el = this.rootEl.querySelector('.option-desk-body');
+        this._closeBtn = this.rootEl.querySelector('.panel-close-btn');
+        this._exportBtn = this.rootEl.querySelector('.panel-export-btn');
+        this._rows = [];
+        this._context = {};
+        this._places = greekScales([], {});
+
+        this._closeBtn?.addEventListener('click', (e) => { e.preventDefault(); this._host.close(); });
+        this._exportBtn?.addEventListener('click', (e) => { e.preventDefault(); this._export(); });
+
+        const head = this.rootEl.querySelector('.option-desk-table thead');
+        this._grid = head && this.el
+            ? new DataGrid<DeskRow>({
+                head: head as HTMLElement,
+                body: this.el,
+                columns: this._columns(),
+                // By strike, ascending. A chain has exactly one order and it is not negotiable:
+                // the strip is read as a ladder, and re-sorting it by any column destroys that.
+                defaultSort: { col: 'strike', dir: 'asc' },
+                rowKey: (r) => String(r.strike),
+                emptyText: this._host.t('NoOptions'),
+                rowClass: (r) => this._rowClass(r),
+                contextMenu: makeGridMenu(this._host),
+                selection: 'multi',
+            })
+            : null;
+
+        // The greeks and the far volatilities are there when wanted and out of the way when not:
+        // a desk is read across, and thirty-six columns at once cannot be.
+        this._grid?.setState({
+            hidden: [
+                'callRho', 'callTheta', 'callHv', 'callTheor',
+                'putRho', 'putTheta', 'putHv', 'putTheor',
+            ],
+        });
+
+        this._host.register(this);
+    }
+
+    dispose(): void {
+        this._grid?.destroy();
+        this._host.unregister(this);
+        try { this.rootEl.remove(); } catch { /* already detached */ }
+    }
+
+    /// Show this chain, priced against this context.
+    ///
+    /// Both together, always: a chain and the underlying it is priced off are one observation,
+    /// and refreshing them separately shows greeks computed from a price that has moved.
+    update(strikes: OptionStrike[], context: OptionChainContext = {}): void {
+        this._context = context ?? {};
+        this._rows = scaleChain(strikes ?? [], this._context);
+        this._places = greekScales(this._rows, this._context);
+        this._grid?.setRows(this._rows);
+    }
+
+    /// The rows as the desk holds them, scales and intrinsic values resolved.
+    rows(): readonly DeskRow[] {
+        return this._rows;
+    }
+
+    _export(): void {
+        this._grid?.download('option-chain', this._host.t('OptionDesk'));
+    }
+
+    // Which side of the money this strike is on. A chain is read from the money outwards, and
+    // the line between the two halves is what a reader finds first.
+    _rowClass(row: DeskRow): string {
+        const asset = this._context.assetPrice;
+        if (asset === null || asset === undefined) return 'option-row';
+        return `option-row ${row.strike < asset ? 'option-itm-call' : 'option-itm-put'}`;
+    }
+
+    _columns(): GridColumn<DeskRow>[] {
+        const label = (key: string) => this._host.t(key);
+
+        const side = (which: 'call' | 'put'): GridColumn<DeskRow>[] => {
+            const prefix = which;
+            const at = (r: DeskRow): OptionSide => r[which];
+            const g = (r: DeskRow): Greeks | null => sideGreeks(r, which, this._context);
+
+            return [
+                { key: `${prefix}Rho`, header: label('Rho'), exportable: true, value: (r) => g(r)?.rho ?? null, render: (r) => decimals(g(r)?.rho, this._places.rho) },
+                { key: `${prefix}Theta`, header: label('Theta'), exportable: true, value: (r) => g(r)?.theta ?? null, render: (r) => decimals(g(r)?.theta, this._places.theta) },
+                { key: `${prefix}Vega`, header: label('Vega'), exportable: true, value: (r) => g(r)?.vega ?? null, render: (r) => decimals(g(r)?.vega, this._places.vega) },
+                { key: `${prefix}Gamma`, header: label('Gamma'), exportable: true, value: (r) => g(r)?.gamma ?? null, render: (r) => decimals(g(r)?.gamma, this._places.gamma) },
+                { key: `${prefix}Delta`, header: label('Delta'), exportable: true, value: (r) => g(r)?.delta ?? null, render: (r) => decimals(g(r)?.delta, this._places.delta) },
+                { key: `${prefix}Bid`, header: label('Bid'), exportable: true, cellClass: () => 'option-bid', value: (r) => at(r).bid ?? null, render: (r) => price(at(r).bid) },
+                { key: `${prefix}Ask`, header: label('Ask'), exportable: true, cellClass: () => 'option-ask', value: (r) => at(r).ask ?? null, render: (r) => price(at(r).ask) },
+                { key: `${prefix}Theor`, header: label('TheorPrice'), exportable: true, value: (r) => at(r).theoretical ?? null, render: (r) => price(at(r).theoretical) },
+                {
+                    key: `${prefix}Volume`, header: label('Volume'), exportable: true,
+                    value: (r) => at(r).volume ?? 0,
+                    render: (r) => this._bar(at(r).volume, which === 'call' ? r.maxCallVolume : r.maxPutVolume, which, formatQty(at(r).volume ?? 0)),
+                    exportValue: (r) => at(r).volume ?? 0,
+                },
+                {
+                    key: `${prefix}Oi`, header: label('OI'), exportable: true,
+                    value: (r) => at(r).openInterest ?? 0,
+                    render: (r) => this._bar(at(r).openInterest, which === 'call' ? r.maxCallOpenInterest : r.maxPutOpenInterest, which, formatQty(at(r).openInterest ?? 0)),
+                    exportValue: (r) => at(r).openInterest ?? 0,
+                },
+                { key: `${prefix}Symbol`, header: which === 'call' ? label('Call') : label('Put'), exportable: true, value: (r) => at(r).symbol ?? '' },
+                {
+                    key: `${prefix}IvBid`, header: label('IVBid'), exportable: true,
+                    value: (r) => at(r).ivBid ?? null,
+                    render: (r) => this._bar(at(r).ivBid, r.maxVolatility, 'iv', percent(at(r).ivBid)),
+                    exportValue: (r) => at(r).ivBid ?? '',
+                },
+                {
+                    key: `${prefix}IvAsk`, header: label('IVAsk'), exportable: true,
+                    value: (r) => at(r).ivAsk ?? null,
+                    render: (r) => this._bar(at(r).ivAsk, r.maxVolatility, 'iv', percent(at(r).ivAsk)),
+                    exportValue: (r) => at(r).ivAsk ?? '',
+                },
+                {
+                    key: `${prefix}IvLast`, header: label('IVLast'), exportable: true,
+                    value: (r) => at(r).ivLast ?? null,
+                    render: (r) => this._bar(at(r).ivLast, r.maxVolatility, 'iv', percent(at(r).ivLast)),
+                    exportValue: (r) => at(r).ivLast ?? '',
+                },
+                {
+                    key: `${prefix}Hv`, header: label('HV'), exportable: true,
+                    value: (r) => at(r).historicalVolatility ?? null,
+                    render: (r) => this._bar(at(r).historicalVolatility, r.maxVolatility, 'iv', percent(at(r).historicalVolatility)),
+                    exportValue: (r) => at(r).historicalVolatility ?? '',
+                },
+            ];
+        };
+
+        // Declared outward from the strike: volatilities and quotes against the middle, where
+        // the two sides are compared, and the greeks out at the edges. The put side is that
+        // same order reflected, which is what makes the chain a mirror rather than a repeat.
+        const puts = side('put').slice().reverse();
+
+        return [
+            ...side('call'),
+            {
+                key: 'strike',
+                header: label('Strike'),
+                exportable: true,
+                cellClass: () => 'option-strike',
+                value: (r) => r.strike,
+                render: (r) => price(r.strike),
+            },
+            {
+                key: 'intrinsic',
+                header: label('IntrinsicValue'),
+                exportable: true,
+                cellClass: () => 'option-intrinsic',
+                // Whichever side is in the money at this strike; the other is worth nothing to
+                // exercise, and showing both would be one number and one zero on every row.
+                value: (r) => Math.max(r.callIntrinsic, r.putIntrinsic),
+                render: (r) => price(Math.max(r.callIntrinsic, r.putIntrinsic)),
+            },
+            ...puts,
+        ];
+    }
+
+    // A figure with its share of the strip behind it. The bar is a width, not a drawing: it
+    // scales with the cell, it prints, and it needs no canvas per row.
+    _bar(value: number | null | undefined, max: number, kind: 'call' | 'put' | 'iv', text: string): string | Node {
+        if (value === null || value === undefined || !isFinite(value) || value <= 0) return text;
+
+        const cell = document.createElement('span');
+        cell.className = 'option-bar-cell';
+
+        const bar = document.createElement('span');
+        bar.className = `option-bar option-bar-${kind}`;
+        bar.style.width = `${Math.min(100, (value / (max || 1)) * 100).toFixed(1)}%`;
+        cell.appendChild(bar);
+
+        const label = document.createElement('span');
+        label.className = 'option-bar-text';
+        label.textContent = text;
+        cell.appendChild(label);
+
+        return cell;
+    }
+}
+
+/// Resolve the bar scales and the intrinsic values over a whole chain.
+///
+/// One pass over every strike, not one per row: a bar means "this much of the busiest strike",
+/// and a scale computed per row would make every row its own maximum.
+export function scaleChain(strikes: readonly OptionStrike[], context: OptionChainContext): DeskRow[] {
+    const asset = context.assetPrice ?? null;
+
+    const maxOf = (pick: (s: OptionSide) => number | null | undefined, sides: (r: OptionStrike) => OptionSide[]): number =>
+        Math.max(0, ...strikes.flatMap(r => sides(r).map(s => pick(s) ?? 0)).filter(v => isFinite(v)));
+
+    const maxCallVolume = maxOf(s => s.volume, r => [r.call]);
+    const maxPutVolume = maxOf(s => s.volume, r => [r.put]);
+    const maxCallOpenInterest = maxOf(s => s.openInterest, r => [r.call]);
+    const maxPutOpenInterest = maxOf(s => s.openInterest, r => [r.put]);
+
+    // One scale across both sides: the comparison a skew IS, is the one between them.
+    const maxVolatility = Math.max(
+        maxOf(s => s.ivBid, r => [r.call, r.put]),
+        maxOf(s => s.ivAsk, r => [r.call, r.put]),
+        maxOf(s => s.ivLast, r => [r.call, r.put]),
+        maxOf(s => s.historicalVolatility, r => [r.call, r.put]),
+    );
+
+    return strikes.map(row => ({
+        ...row,
+        maxCallVolume,
+        maxPutVolume,
+        maxCallOpenInterest,
+        maxPutOpenInterest,
+        maxVolatility,
+        callIntrinsic: asset === null ? 0 : Math.max(0, asset - row.strike),
+        putIntrinsic: asset === null ? 0 : Math.max(0, row.strike - asset),
+    }));
+}
+
+/// The greeks for one side: the host's if it sent them, otherwise computed from its volatility.
+///
+/// Null when neither is possible - no volatility, or nothing to price against. A blank is the
+/// honest answer there; a zero would read as a measured delta of nothing.
+export function sideGreeks(row: OptionStrike, which: 'call' | 'put', context: OptionChainContext): Greeks | null {
+    const side = row[which];
+    if (side.greeks !== undefined) return side.greeks;
+
+    const deviation = side.ivLast ?? side.ivBid ?? side.ivAsk ?? side.historicalVolatility ?? null;
+    const assetPrice = context.assetPrice ?? null;
+    const timeToExpiry = context.timeToExpiry ?? null;
+
+    if (deviation === null || assetPrice === null || timeToExpiry === null) return null;
+
+    return computeGreeks(which === 'call' ? OptionTypes.Call : OptionTypes.Put, {
+        assetPrice,
+        strike: row.strike,
+        timeToExpiry,
+        riskFree: context.riskFree ?? 0,
+        dividend: context.dividend ?? 0,
+        deviation,
+    });
+}
+
+/// Every greek this desk can show. Order is the order a chain is read in, outwards from delta.
+const GREEK_KEYS = ['delta', 'gamma', 'vega', 'theta', 'rho'] as const;
+
+/// Three significant digits for the smallest figure in a column, within bounds a column can hold.
+const GREEK_DIGITS = 4;
+const GREEK_MIN_PLACES = 2;
+const GREEK_MAX_PLACES = 8;
+
+/// How many decimal places a column of greeks needs.
+///
+/// One count cannot serve every greek: a delta is about one, while a gamma on an underlying at
+/// 60000 is about 0.00003, and the four places that suit the first show every strike of the
+/// second as 0.0000 - a column that is present, aligned, and says nothing. So the count comes
+/// from the numbers, sized to the smallest of them.
+///
+/// One count for the whole column, not per cell: a column of figures is read down its decimal
+/// point, and a ragged one is read a cell at a time.
+export function greekPlaces(values: readonly (number | null | undefined)[]): number {
+    const scale = Math.min(...values
+        .filter((v): v is number => typeof v === 'number' && isFinite(v) && v !== 0)
+        .map(Math.abs));
+
+    // Nothing measurable: a zero column is a zero column at any width.
+    if (!isFinite(scale)) return GREEK_MIN_PLACES;
+
+    const places = GREEK_DIGITS - 1 - Math.floor(Math.log10(scale));
+    return Math.min(GREEK_MAX_PLACES, Math.max(GREEK_MIN_PLACES, places));
+}
+
+/// The places for each greek, measured across both sides of the chain at once.
+///
+/// Across both sides deliberately: the desk mirrors, and a gamma written to eight places on the
+/// left and five on the right stops being a mirror.
+export function greekScales(rows: readonly OptionStrike[], context: OptionChainContext): Record<keyof Greeks, number> {
+    const all = rows
+        .flatMap(r => [sideGreeks(r, OptionTypes.Call, context), sideGreeks(r, OptionTypes.Put, context)])
+        .filter((g): g is Greeks => g !== null);
+
+    const places = {} as Record<keyof Greeks, number>;
+    for (const key of GREEK_KEYS) places[key] = greekPlaces(all.map(g => g[key]));
+    return places;
+}
+
+function decimals(value: number | null | undefined, places: number): string {
+    if (value === null || value === undefined || !isFinite(value)) return '';
+    return value.toFixed(places);
+}
+
+function price(value: number | null | undefined): string {
+    if (value === null || value === undefined || !isFinite(value)) return '';
+    return formatPrice(value);
+}
+
+/// A volatility, as the points a desk quotes it in rather than the fraction it is held as.
+function percent(value: number | null | undefined): string {
+    if (value === null || value === undefined || !isFinite(value)) return '';
+    return `${(value * 100).toFixed(2)}%`;
+}

package/src/pnl-curve.ts

@@ -0,0 +1,204 @@
+// The geometry of a cumulative P&L curve, as pure functions over numbers.
+//
+// The same curve is read in three places and drawn at three sizes: a strategy row's sparkline,
+// a statistics card, and a backtest's own chart. Only the last of those is a price chart - it
+// shares the price axis and belongs to the chart engine. The other two are a curve in a box,
+// and this is that curve: where each point lands, where the baseline sits, and which way the
+// run ended. No canvas, so it can be checked against arithmetic rather than against pixels.
+
+/// One sample of a run's cumulative P&L. Time is whatever the caller counts in - seconds, unix
+/// milliseconds - because only the spacing between samples is used, never the absolute value.
+export interface PnlPoint {
+    time: number;
+    value: number;
+}
+
+/// The box one curve fills, in device pixels. The padding keeps a curve at its extreme off the
+/// edge, where a stroke would be clipped in half.
+export interface PnlBox {
+    width: number;
+    height: number;
+    padX: number;
+    padY: number;
+}
+
+export interface PnlCurve {
+    /// The curve, in draw order.
+    points: [number, number][];
+    /// The curve closed down to the baseline, ready to fill.
+    area: [number, number][];
+    /// Y of zero P&L. Always inside the box: the range is widened to include it.
+    zeroY: number;
+    /// The value range the box covers, zero included.
+    min: number;
+    max: number;
+    /// Whether the run ended at or above where it started. What the curve is coloured by - and
+    /// the last value, not the highest: a run that peaked and gave it all back is a loss.
+    positive: boolean;
+}
+
+/// A run reduced to at most `count` samples, spanning the same stretch of time.
+///
+/// A sparkline that keeps only the newest N samples marches sideways: each new sample pushes the
+/// oldest off the left edge, so the shape slides and the run's beginning is lost. Compressing
+/// instead keeps the whole run in the box and re-buckets it, so a new sample changes the curve's
+/// shape rather than its position - which is what makes two readings of the same strategy
+/// comparable.
+///
+/// A bucket is summarised by its LAST sample, not by an average. This is a cumulative figure:
+/// the last value in a bucket is where the run actually stood at that moment, while an average
+/// would draw a rising run below the line it was on. Every point returned is therefore a real
+/// sample, never a computed one, and the first and last are kept exactly - they are where the
+/// run started and where it stands now.
+export function compressPnl(points: readonly PnlPoint[], count: number): PnlPoint[] {
+    if (points.length <= count || count < 2) return points.slice();
+
+    const first = points[0];
+    const last = points[points.length - 1];
+    const span = last.time - first.time;
+
+    // Every sample at the same instant: there is no time to bucket by, so fall back to position.
+    if (!(span > 0)) {
+        const step = (points.length - 1) / (count - 1);
+        return Array.from({ length: count }, (_, i) => points[Math.round(i * step)]);
+    }
+
+    // One bucket per output point, the last sample in each standing for it. Buckets that caught
+    // nothing are skipped rather than repeated, so a quiet stretch reads as a long flat segment
+    // instead of as a row of identical points.
+    // `count - 1` buckets, not `count`: the first sample is seeded and the last is appended, so
+    // the buckets between them may contribute at most `count - 2` points. Sized any wider the
+    // result can overrun `count`, and trimming it afterwards would drop the run's start - the
+    // one point this function exists to keep.
+    const buckets = count - 1;
+    const out: PnlPoint[] = [first];
+    let bucket = 0;
+    for (let i = 1; i < points.length; i++) {
+        const index = Math.min(buckets - 1, Math.floor(((points[i].time - first.time) / span) * buckets));
+        if (index > bucket) {
+            out.push(points[i - 1]);
+            bucket = index;
+        }
+    }
+    if (out[out.length - 1] !== last) out.push(last);
+
+    return out;
+}
+
+/// Lay a run out in a box, or null when there is no curve to draw.
+///
+/// Two rules that are not arbitrary. Zero is always in the range, so a run that only ever won
+/// still shows the line it started from and the height of the curve means something. And the
+/// horizontal axis is time, not sample index: a strategy that traded twice in the morning and
+/// forty times after lunch should look like that, not like a curve with evenly spaced steps.
+export function pnlCurve(points: readonly PnlPoint[], box: PnlBox): PnlCurve | null {
+    const clean = points
+        .filter(p => p !== null && p !== undefined && Number.isFinite(p.time) && Number.isFinite(p.value))
+        .slice()
+        .sort((a, b) => a.time - b.time);
+
+    if (clean.length < 2) return null;
+
+    // One sample per drawable pixel is as much as a box can show; past that the extra points are
+    // strokes on top of strokes. Compressing here rather than asking the caller to do it is what
+    // lets a host keep the whole run and still get a curve that does not slide.
+    const drawable = Math.max(2, Math.round(box.width - box.padX * 2));
+    const shown = compressPnl(clean, drawable);
+
+    const values = shown.map(p => p.value);
+    const min = Math.min(0, ...values);
+    const max = Math.max(0, ...values);
+
+    const left = box.padX;
+    const right = box.width - box.padX;
+    const top = box.padY;
+    const bottom = box.height - box.padY;
+
+    const firstTime = shown[0].time;
+    const lastTime = shown[shown.length - 1].time;
+    const timeSpan = lastTime - firstTime;
+    const valueSpan = max - min;
+
+    // A run with no spread in one axis collapses onto a line rather than dividing by nothing:
+    // every sample at the same instant stacks at the left edge, every sample at the same value
+    // rests on the top edge, which for a flat run is also its baseline.
+    const x = (time: number): number => (timeSpan === 0 ? left : left + ((time - firstTime) / timeSpan) * (right - left));
+    const y = (value: number): number => (valueSpan === 0 ? top : bottom - ((value - min) / valueSpan) * (bottom - top));
+
+    const curve = shown.map(p => [x(p.time), y(p.value)] as [number, number]);
+    const zeroY = y(0);
+
+    return {
+        points: curve,
+        // Closed along the baseline rather than along the foot of the box: a run entirely above
+        // water fills the gap between itself and zero, and nothing below it.
+        area: [...curve, [curve[curve.length - 1][0], zeroY], [curve[0][0], zeroY]],
+        zeroY,
+        min,
+        max,
+        positive: shown[shown.length - 1].value >= 0,
+    };
+}
+
+/// What a curve is drawn with. Colours come from the caller because the page owns its palette;
+/// the two directions are the same pair every other control uses for up and down.
+export interface PnlCurveStyle {
+    up: string;
+    down: string;
+    /// The zero line. A curve is read against it, so it is drawn even when nothing crosses it.
+    baseline: string;
+    lineWidth: number;
+    /// How much of the direction colour the filled area keeps, 0 to 1.
+    fillOpacity: number;
+}
+
+/// The 2D calls one paint makes. Narrow on purpose: a test supplies a recorder, and a control
+/// that started reaching for something else shows up here rather than in a screenshot.
+export interface PnlCurveContext {
+    clearRect(x: number, y: number, w: number, h: number): void;
+    beginPath(): void;
+    moveTo(x: number, y: number): void;
+    lineTo(x: number, y: number): void;
+    closePath(): void;
+    stroke(): void;
+    fill(): void;
+    setLineDash(segments: number[]): void;
+    globalAlpha: number;
+    // The browser's own type for these, so a real 2D context satisfies this contract as
+    // it stands: it accepts a gradient or a pattern where this only ever writes a colour.
+    strokeStyle: string | CanvasGradient | CanvasPattern;
+    fillStyle: string | CanvasGradient | CanvasPattern;
+    lineWidth: number;
+}
+
+/// Paint a laid-out curve: the baseline, the filled area under it, then the line itself.
+export function drawPnlCurve(ctx: PnlCurveContext, curve: PnlCurve, box: PnlBox, style: PnlCurveStyle): void {
+    const colour = curve.positive ? style.up : style.down;
+
+    ctx.clearRect(0, 0, box.width, box.height);
+
+    ctx.setLineDash([2, 3]);
+    ctx.strokeStyle = style.baseline;
+    ctx.lineWidth = 1;
+    ctx.beginPath();
+    ctx.moveTo(box.padX, curve.zeroY);
+    ctx.lineTo(box.width - box.padX, curve.zeroY);
+    ctx.stroke();
+    ctx.setLineDash([]);
+
+    ctx.globalAlpha = style.fillOpacity;
+    ctx.fillStyle = colour;
+    ctx.beginPath();
+    ctx.moveTo(curve.area[0][0], curve.area[0][1]);
+    for (const [px, py] of curve.area.slice(1)) ctx.lineTo(px, py);
+    ctx.closePath();
+    ctx.fill();
+    ctx.globalAlpha = 1;
+
+    ctx.strokeStyle = colour;
+    ctx.lineWidth = style.lineWidth;
+    ctx.beginPath();
+    ctx.moveTo(curve.points[0][0], curve.points[0][1]);
+    for (const [px, py] of curve.points.slice(1)) ctx.lineTo(px, py);
+    ctx.stroke();
+}