@matchstick-trading/primitives 0.0.10

package/src/core/symbol-search.ts

@@ -0,0 +1,256 @@
+/**
+ * The matching rules of the symbol search as plain functions. The host owns the instrument list;
+ * this owns matching. Ideas, not code, come from the old symbol trie (a character trie, no licence on record): it
+ * is replaced here by sorted arrays and binary search, and by no regular expression at all, so no typed character
+ * can make `searchSymbols` throw.
+ *
+ * Order of results: an exact symbol, then a symbol that starts with the text, then an exact alias, then an alias or a
+ * name word that starts with the text. When more than one word is typed, each must start a different word of the symbol, name
+ * or aliases; those matches rank with the word matches. Inside a group: the shorter symbol, then A to Z, then venue, then list order.
+ * Typo tolerance is deliberately not here: in a ticker box a typo can pick the wrong instrument.
+ */
+export interface Instrument {
+  /** Unique within the list. */
+  id: string;
+  symbol: string;
+  venue: string;
+  name?: string;
+  aliases?: readonly string[];
+  kind?: string;
+  /** YYYY-MM-DD, for contracts that expire. */
+  expires?: string;
+}
+
+export type MatchedOn = 'symbol' | 'alias' | 'name';
+export type MatchHow = 'exact' | 'prefix' | 'word';
+
+export interface SymbolMatch {
+  instrument: Instrument;
+  matchedOn: MatchedOn;
+  how: MatchHow;
+  /** 0 is best. */
+  rank: number;
+}
+
+export interface SearchOptions {
+  /** At most this many rows; default 20, clamped to 1..200. */
+  limit?: number;
+  venue?: string;
+  kind?: string;
+}
+
+interface Entry {
+  instrument: Instrument;
+  order: number;
+  symbolKey: string;
+  venueKey: string;
+  kindKey: string;
+  /** Every word of the symbol, name and aliases, built when a multi-word query first needs it. */
+  parts?: Part[];
+}
+interface Part { word: string; on: MatchedOn }
+interface Keyed { key: string; entry: Entry; on: MatchedOn }
+
+export interface SymbolIndex {
+  /** Records kept. */
+  readonly size: number;
+  /** Records dropped because id, symbol or venue was not a non-empty string, or the id repeated. */
+  readonly skipped: number;
+  /** @internal */ readonly entries: readonly Entry[];
+  /** @internal */ readonly bySymbol: readonly Keyed[];
+  /** @internal */ words: Keyed[] | null;
+  /** @internal */ tails: Keyed[] | null;
+}
+
+const DEFAULT_LIMIT = 20;
+const MAX_LIMIT = 200;
+const MAX_QUERY = 64;
+
+/** Upper case, Unicode-composed, spaces collapsed. Total: it accepts any string, including lone surrogates. */
+export function normalizeSymbolText(text: unknown): string {
+  return fold(text).slice(0, MAX_QUERY);
+}
+
+function fold(text: unknown): string {
+  if (typeof text !== 'string') return '';
+  let s = text;
+  try { s = s.normalize('NFKC'); } catch { /* keep the text as typed */ }
+  return s.toUpperCase().replace(/\s+/g, ' ').trim();
+}
+
+/** The words of a value, each cut to the query length: split first, so a word past the 64th character is still found. */
+const wordsOf = (value: unknown): string[] => (text(value) ? fold(value).split(' ').filter(Boolean).map((w) => w.slice(0, MAX_QUERY)) : []);
+
+const text = (v: unknown): v is string => typeof v === 'string' && v.trim() !== '';
+
+const byKey = (a: Keyed, b: Keyed) => (a.key < b.key ? -1 : a.key > b.key ? 1 : a.entry.order - b.entry.order);
+
+/** Indexes the symbols now; names and aliases on the first search that needs them. Never throws. */
+export function buildSymbolIndex(instruments: readonly Instrument[]): SymbolIndex {
+  const entries: Entry[] = [];
+  const seen = new Set<string>();
+  let skipped = 0;
+  for (const instrument of instruments ?? []) {
+    if (!instrument || !text(instrument.id) || !text(instrument.symbol) || !text(instrument.venue) || seen.has(instrument.id)) { skipped++; continue; }
+    seen.add(instrument.id);
+    entries.push({ instrument, order: entries.length, symbolKey: normalizeSymbolText(instrument.symbol), venueKey: normalizeSymbolText(instrument.venue), kindKey: normalizeSymbolText(instrument.kind) });
+  }
+  const bySymbol = entries.map((entry): Keyed => ({ key: entry.symbolKey, entry, on: 'symbol' })).sort(byKey);
+  return { size: entries.length, skipped, entries, bySymbol, words: null, tails: null };
+}
+
+function wordIndex(index: SymbolIndex): Keyed[] {
+  if (index.words) return index.words;
+  const words: Keyed[] = [];
+  for (const entry of index.entries) {
+    const { name, aliases } = entry.instrument;
+    for (const w of wordsOf(name)) words.push({ key: w, entry, on: 'name' });
+    if (Array.isArray(aliases)) for (const alias of aliases) if (text(alias)) words.push({ key: normalizeSymbolText(alias), entry, on: 'alias' });
+  }
+  return (index.words = words.sort(byKey));
+}
+
+function entryParts(entry: Entry): Part[] {
+  if (entry.parts) return entry.parts;
+  const { symbol, name, aliases } = entry.instrument;
+  const parts: Part[] = wordsOf(symbol).map((word): Part => ({ word, on: 'symbol' })); // a symbol can hold spaces
+  for (const w of wordsOf(name)) parts.push({ word: w, on: 'name' });
+  if (Array.isArray(aliases)) for (const alias of aliases) for (const w of wordsOf(alias)) parts.push({ word: w, on: 'alias' });
+  return (entry.parts = parts);
+}
+
+/**
+ * The second and later words of symbols and aliases, for queries of more than one word; built on first use. The
+ * symbol index and the word index already start at every name word and at the first word of each symbol and alias,
+ * so only these are missing, and in most lists there are few of them.
+ */
+function tailIndex(index: SymbolIndex): Keyed[] {
+  if (index.tails) return index.tails;
+  const tails: Keyed[] = [];
+  for (const entry of index.entries) {
+    const { symbol, aliases } = entry.instrument;
+    for (const w of wordsOf(symbol).slice(1)) tails.push({ key: w, entry, on: 'symbol' });
+    if (Array.isArray(aliases)) for (const alias of aliases) for (const w of wordsOf(alias).slice(1)) tails.push({ key: w, entry, on: 'alias' });
+  }
+  return (index.tails = tails.sort(byKey));
+}
+
+/** First position whose key is >= `prefix`. */
+function lowerBound(list: readonly Keyed[], prefix: string): number {
+  let lo = 0;
+  let hi = list.length;
+  while (lo < hi) {
+    const mid = (lo + hi) >>> 1;
+    if (list[mid].key < prefix) lo = mid + 1; else hi = mid;
+  }
+  return lo;
+}
+
+function compare(a: SymbolMatch, b: SymbolMatch): number {
+  return a.rank - b.rank
+    || a.instrument.symbol.length - b.instrument.symbol.length
+    || (a.instrument.symbol < b.instrument.symbol ? -1 : a.instrument.symbol > b.instrument.symbol ? 1 : 0)
+    || (a.instrument.venue < b.instrument.venue ? -1 : a.instrument.venue > b.instrument.venue ? 1 : 0);
+}
+
+/** Ranked rows for `query`, at most `limit`. An empty or odd query gives no rows; it never throws. */
+export function searchSymbols(index: SymbolIndex, query: string, options: SearchOptions = {}): SymbolMatch[] {
+  try {
+    const q = normalizeSymbolText(query);
+    if (q === '') return [];
+    const limit = Math.min(MAX_LIMIT, Math.max(1, Math.floor(Number.isFinite(options.limit) ? (options.limit as number) : DEFAULT_LIMIT)));
+    const venue = options.venue ? normalizeSymbolText(options.venue) : null;
+    const kind = options.kind ? normalizeSymbolText(options.kind) : null;
+    // The best `limit` rows so far, in order. A word index can hold tens of thousands of hits for one letter,
+    // so keep a short sorted list instead of collecting and sorting them all.
+    const top: Array<{ match: SymbolMatch; order: number }> = [];
+    const before = (match: SymbolMatch, order: number, other: { match: SymbolMatch; order: number }) => (compare(match, other.match) || order - other.order) < 0; // last tie-break: list order
+    const consider = (hit: Keyed, how: MatchHow, rank: number) => {
+      const { instrument, order, venueKey, kindKey } = hit.entry;
+      if (venue && venueKey !== venue) return;
+      if (kind && kindKey !== kind) return;
+      const match: SymbolMatch = { instrument, matchedOn: hit.on, how, rank };
+      const at = top.findIndex((t) => t.order === order);
+      if (at >= 0) {
+        if (top[at].match.rank <= rank) return; // already here with an equal or better match
+        top.splice(at, 1);
+      } else if (top.length >= limit && before(match, order, top[top.length - 1]) === false) return;
+      let i = top.length;
+      while (i > 0 && before(match, order, top[i - 1])) i--;
+      top.splice(i, 0, { match, order });
+      if (top.length > limit) top.pop();
+    };
+    // Symbols: the sorted run that starts with q; the exact ones sort first inside it.
+    for (let i = lowerBound(index.bySymbol, q); i < index.bySymbol.length && index.bySymbol[i].key.startsWith(q); i++) {
+      const hit = index.bySymbol[i];
+      consider(hit, hit.key === q ? 'exact' : 'prefix', hit.key === q ? 0 : 1);
+    }
+    // Aliases and name words rank below every symbol match, so a full list of symbol matches needs no further look
+    // (and the name index is built on the first search that needs it, not at indexing time).
+    if (top.length < limit || top[top.length - 1].match.rank > 1) {
+      const words = wordIndex(index);
+      for (let i = lowerBound(words, q); i < words.length && words[i].key.startsWith(q); i++) {
+        const hit = words[i];
+        if (hit.on === 'alias') consider(hit, hit.key === q ? 'exact' : 'prefix', hit.key === q ? 2 : 3);
+        else consider(hit, 'word', 3);
+      }
+    }
+    // More than one word typed ("apple inc", "dec 2026"): every word must start a different word of the symbol, name
+    // or aliases, so "dec dec" needs two DECs. The longest word picks the candidates; the rest are checked on each.
+    // Ranked with the word matches.
+    if (q.includes(' ') && (top.length < limit || top[top.length - 1].match.rank > 2)) {
+      // Longest first: two typed words that fit the same word are prefixes of each other, so the longer one is the
+      // pickier and claims a word first; then a greedy pass finds a fit whenever one exists.
+      const tokens = q.split(' ').filter(Boolean).sort((a, b) => b.length - a.length);
+      const driver = tokens[0];
+      const done = new Set<number>();
+      let taken = new Uint8Array(16);
+      const check = (entry: Entry) => {
+        if (done.has(entry.order)) return;
+        done.add(entry.order);
+        const words = entryParts(entry);
+        if (words.length > taken.length) taken = new Uint8Array(words.length); else taken.fill(0, 0, words.length);
+        let onSymbol = false;
+        let onName = false;
+        for (const t of tokens) {
+          let k = 0;
+          while (k < words.length && (taken[k] === 1 || !words[k].word.startsWith(t))) k++;
+          if (k === words.length) return;
+          taken[k] = 1;
+          if (words[k].on === 'symbol') onSymbol = true; else if (words[k].on === 'name') onName = true;
+        }
+        consider({ key: q, entry, on: onSymbol ? 'symbol' : onName ? 'name' : 'alias' }, 'word', 3);
+      };
+      // Candidates: every entry with a word that starts with the driver (a symbol, a name word, an alias, or a later word of a symbol or alias).
+      for (const list of [index.bySymbol, wordIndex(index), tailIndex(index)]) {
+        for (let i = lowerBound(list, driver); i < list.length && list[i].key.startsWith(driver); i++) check(list[i].entry);
+      }
+    }
+    return top.map((t) => t.match);
+  } catch {
+    return []; // the contract of this function: a result list, never an exception
+  }
+}
+
+/** Resolves the key a user pressed in the search box. */
+export type SymbolKeyAction = 'next' | 'previous' | 'pick' | 'close' | 'clear';
+interface KeyLike { key: string; ctrlKey: boolean; metaKey: boolean; altKey: boolean; isComposing?: boolean }
+
+/** ArrowDown/Up move, Enter picks, Escape closes the list and a second Escape clears the text. Not while composing text (IME). */
+export function resolveSymbolKey(event: KeyLike, state: { open: boolean; hasText: boolean }): SymbolKeyAction | null {
+  if (event.ctrlKey || event.metaKey || event.altKey || event.isComposing) return null;
+  switch (event.key) {
+    case 'ArrowDown': return 'next';
+    case 'ArrowUp': return 'previous';
+    case 'Enter': return state.open ? 'pick' : null;
+    case 'Escape': return state.open ? 'close' : state.hasText ? 'clear' : null;
+    default: return null;
+  }
+}
+
+/** The row index a move lands on; the ends stop (no wrap). With no row active, next lands on 0 and previous on the last. */
+export function nextSymbolIndex(count: number, current: number, action: 'next' | 'previous'): number {
+  if (count === 0) return -1;
+  if (current < 0 || current >= count) return action === 'next' ? 0 : count - 1;
+  return Math.min(count - 1, Math.max(0, current + (action === 'next' ? 1 : -1)));
+}

package/src/core/tape.ts

@@ -0,0 +1,159 @@
+/**
+ * The rules of the trade tape as plain functions. A trade is a time, a price, a size and a side. Price and size arrive and
+ * stay exact decimal strings and are printed as given; time is an ISO-8601 UTC instant. A row that breaks a rule is
+ * reported with its place in the input and is never drawn. Nothing here repairs a row, reads a clock or touches a page.
+ */
+
+export type TapeSide = 'buy' | 'sell' | 'unknown';
+
+/** One trade as the host records it. `side` is the aggressor when the feed says so; `unknown` when it does not. */
+export interface TapeTrade {
+  /** A stable id from the feed, such as a sequence number. Leave it out and the row's place in the list is used, which changes if the host drops old rows. */
+  id?: string;
+  /** ISO-8601 UTC, for example `2026-01-05T14:30:05.123Z`. Rows come oldest first and never go back in time. */
+  t: string;
+  /** Exact decimal string, above zero. */
+  price: string;
+  /** Exact decimal string, above zero. */
+  size: string;
+  side: TapeSide;
+}
+
+/** A trade that passed the rules, with the id it keeps while the host adds rows after it. */
+export interface TapeRow extends TapeTrade {
+  /** The trade's `id`, or its place in the input as text. */
+  id: string;
+  /** `14:30:05.123`: the UTC clock time, as recorded. */
+  time: string;
+}
+
+export interface TapeIssue {
+  /** The row's place in the input. */
+  index: number;
+  message: string;
+}
+
+export interface TapeRead {
+  /** Valid rows, oldest first, as given. */
+  rows: TapeRow[];
+  issues: TapeIssue[];
+}
+
+export const TAPE_SIDE_LABEL: Record<TapeSide, string> = { buy: 'Buy', sell: 'Sell', unknown: 'Unknown' };
+
+const ISO_UTC = /^(\d{4})-(\d{2})-(\d{2})T([01]\d|2[0-3]):([0-5]\d):([0-5]\d)(\.\d+)?Z$/;
+const POSITIVE_DECIMAL = /^\d+(?:\.\d+)?$/;
+
+function isIsoUtc(value: unknown): value is string {
+  if (typeof value !== 'string') return false;
+  const m = ISO_UTC.exec(value);
+  if (!m) return false;
+  const d = new Date(Date.UTC(Number(m[1]), Number(m[2]) - 1, Number(m[3])));
+  return d.getUTCFullYear() === Number(m[1]) && d.getUTCMonth() === Number(m[2]) - 1 && d.getUTCDate() === Number(m[3]);
+}
+
+function isPositiveDecimal(value: unknown): value is string {
+  return typeof value === 'string' && POSITIVE_DECIMAL.test(value) && /[1-9]/.test(value);
+}
+
+/** Order two valid ISO-8601 UTC instants at the precision written, so fractions past milliseconds still count. */
+function compareInstants(a: string, b: string): number {
+  const [aMain, aFrac = ''] = a.slice(0, -1).split('.');
+  const [bMain, bFrac = ''] = b.slice(0, -1).split('.');
+  if (aMain !== bMain) return aMain < bMain ? -1 : 1;
+  const width = Math.max(aFrac.length, bFrac.length);
+  const x = aFrac.padEnd(width, '0');
+  const y = bFrac.padEnd(width, '0');
+  return x === y ? 0 : x < y ? -1 : 1;
+}
+
+/** The clock part of an ISO-8601 UTC instant, fraction kept as recorded: `14:30:05.123`. */
+export const tapeTime = (t: string): string => t.slice(11, -1);
+
+/**
+ * Check the trades at the boundary. Every problem is returned in one pass. A row earlier than the row before it is
+ * reported and left out; rows at the same instant are fine (one order can fill in several prints).
+ */
+export function readTape(input: unknown): TapeRead {
+  const rows: TapeRow[] = [];
+  const issues: TapeIssue[] = [];
+  if (!Array.isArray(input)) return { rows, issues: [{ index: -1, message: 'expected a list of trades' }] };
+  let last: string | null = null;
+  const seen = new Set<string>();
+  input.forEach((item: unknown, index) => {
+    if (typeof item !== 'object' || item === null || Array.isArray(item)) { issues.push({ index, message: 'expected a trade object' }); return; }
+    const { id, t, price, size, side } = item as Record<string, unknown>;
+    const problems: string[] = [];
+    if (!isIsoUtc(t)) problems.push('t must be an ISO-8601 UTC time ending in Z');
+    if (!isPositiveDecimal(price)) problems.push('price must be an exact decimal string above zero');
+    if (!isPositiveDecimal(size)) problems.push('size must be an exact decimal string above zero');
+    if (side !== 'buy' && side !== 'sell' && side !== 'unknown') problems.push('side must be "buy", "sell" or "unknown"');
+    if (id !== undefined && (typeof id !== 'string' || id === '')) problems.push('id must be a non-empty string when given');
+    if (problems.length) { issues.push({ index, message: problems.join('; ') }); return; }
+    if (last !== null && compareInstants(t as string, last) < 0) { issues.push({ index, message: 'earlier than the row before it' }); return; }
+    const rowId = typeof id === 'string' ? id : String(index);
+    if (seen.has(rowId)) { issues.push({ index, message: `id "${rowId}" is already used` }); return; }
+    seen.add(rowId);
+    last = t as string;
+    rows.push({ id: rowId, t: t as string, price: price as string, size: size as string, side: side as TapeSide, time: tapeTime(t as string) });
+  });
+  return { rows, issues };
+}
+
+/** Newest first, the order a tape is read in. The input is not changed. */
+export const newestFirst = (rows: readonly TapeRow[]): TapeRow[] => [...rows].reverse();
+
+/**
+ * While the pointer or focus is on the tape, rows hold their place: the rows shown at that moment stay, in order, and
+ * rows that arrived since are counted, not inserted. `held` is newest first, the order the tape shows. Ids that have left the host's window leave the list.
+ */
+export function holdTape(held: readonly string[], rows: readonly TapeRow[]): { rows: TapeRow[]; waiting: number } {
+  const byId = new Map(rows.map((row) => [row.id, row]));
+  const kept = held.flatMap((id) => { const row = byId.get(id); return row ? [row] : []; });
+  // Rows come oldest first, so what arrived since is whatever sits after the newest row that was held. A rolling window
+  // drops the oldest rows first, so if the newest held row is gone, every row now in the window is newer.
+  const newest = held.length ? rows.findIndex((row) => row.id === held[0]) : -1;
+  return { rows: kept, waiting: newest >= 0 ? rows.length - 1 - newest : rows.length };
+}
+
+/**
+ * One sentence for a polite live region: how many trades, how the sides split, the last print. It is a summary of the
+ * rows given (oldest first), not a line per trade; the caller decides how often to refresh it.
+ */
+export function tapeSummary(rows: readonly TapeRow[]): string {
+  if (rows.length === 0) return 'No trades yet.';
+  const count = { buy: 0, sell: 0, unknown: 0 };
+  for (const row of rows) count[row.side] += 1;
+  const last = rows[rows.length - 1];
+  const parts = [`${count.buy} buy`, `${count.sell} sell`];
+  if (count.unknown) parts.push(`${count.unknown} side unknown`);
+  return `${rows.length} ${rows.length === 1 ? 'trade' : 'trades'}: ${parts.join(', ')}. Last: ${last.side === 'unknown' ? 'side unknown,' : last.side} ${last.size} at ${last.price}, ${last.time} UTC.`;
+}
+
+export type TapeMove = 'next' | 'prev' | 'first' | 'last';
+export type TapeKeyAction = { type: 'move'; to: TapeMove } | { type: 'select' };
+
+interface KeyLike { key: string; ctrlKey: boolean; metaKey: boolean; altKey: boolean }
+
+/** Arrow keys move between rows, Home is the newest row, End the oldest; Enter or Space picks the row. Nothing places an order. */
+export function resolveTapeKey(event: KeyLike): TapeKeyAction | null {
+  if (event.ctrlKey || event.metaKey || event.altKey) return null;
+  switch (event.key) {
+    case 'ArrowDown': return { type: 'move', to: 'next' };
+    case 'ArrowUp': return { type: 'move', to: 'prev' };
+    case 'Home': return { type: 'move', to: 'first' };
+    case 'End': return { type: 'move', to: 'last' };
+    case 'Enter':
+    case ' ': return { type: 'select' };
+    default: return null;
+  }
+}
+
+/** The row index a move lands on; the ends stop. With no current row, next and first land on 0. */
+export function nextTapeIndex(count: number, current: number, to: TapeMove): number {
+  if (count === 0) return -1;
+  if (to === 'first') return 0;
+  if (to === 'last') return count - 1;
+  if (current < 0) return to === 'next' ? 0 : count - 1;
+  return Math.min(count - 1, Math.max(0, current + (to === 'next' ? 1 : -1)));
+}

package/src/core/volume-profile.ts

@@ -0,0 +1,116 @@
+/**
+ * A volume profile as plain functions: how much traded at each price level over a run of bars. Each bar's volume is
+ * spread evenly over the price rows its high-low range touches. Nothing here throws: an empty run, a flat price range or
+ * zero volume gives a profile with no point of control (`poc` is -1, `vah` and `val` are null).
+ */
+import type { CandleBar } from './chart-scale.js';
+
+export interface ProfileRow {
+  /** Bottom and top price of the row. */
+  low: number;
+  high: number;
+  volume: number;
+  /** The part of `volume` from bars that closed up, and from bars that closed down. A bar that closed where it opened counts half each. */
+  upVolume: number;
+  downVolume: number;
+}
+
+export interface VolumeProfileOptions {
+  /** First and last bar index of the run, inclusive. */
+  first: number;
+  last: number;
+  /** Number of price rows, 1 to 500. Default 24. */
+  rows?: number;
+  /** Share of the volume the value area holds, above 0 up to 1. Default 0.7. */
+  valueArea?: number;
+}
+
+export interface VolumeProfileResult {
+  /** Lowest price first. */
+  rows: ProfileRow[];
+  /** Index of the point of control: the row with the most volume (the lowest one on a tie). -1 when there is no volume. */
+  poc: number;
+  /** Top of the highest row and bottom of the lowest row in the value area. Null when there is no volume. */
+  vah: number | null;
+  val: number | null;
+  /** The value area as row indexes [low, high]; [-1, -1] when there is none. */
+  valueAreaRows: [number, number];
+  total: number;
+}
+
+const EMPTY: VolumeProfileResult = { rows: [], poc: -1, vah: null, val: null, valueAreaRows: [-1, -1], total: 0 };
+
+/**
+ * The profile of bars first..last. The value area starts at the point of control and takes whichever neighbouring row
+ * has more volume (the one above on a tie), one row at a time, until it holds the `valueArea` share of the total.
+ */
+export function volumeProfile(bars: readonly CandleBar[], options: VolumeProfileOptions): VolumeProfileResult {
+  const first = Math.max(0, Math.floor(Number.isFinite(options.first) ? options.first : 0));
+  const last = Math.min(bars.length - 1, Math.floor(Number.isFinite(options.last) ? options.last : -1));
+  const count = Math.min(500, Math.max(1, Math.floor(Number.isFinite(options.rows) ? options.rows! : 24)));
+  const share = options.valueArea !== undefined && Number.isFinite(options.valueArea) && options.valueArea > 0 ? Math.min(1, options.valueArea) : 0.7;
+
+  let min = Infinity;
+  let max = -Infinity;
+  // The same bars as the allocation below: one with no volume would stretch the rows without adding to them.
+  for (let i = first; i <= last; i++) {
+    const { high, low, volume } = bars[i];
+    if (!Number.isFinite(high) || !Number.isFinite(low) || !Number.isFinite(volume) || volume <= 0) continue;
+    if (low < min) min = low;
+    if (high > max) max = high;
+  }
+  if (!(max >= min)) return { ...EMPTY, rows: [], valueAreaRows: [-1, -1] };
+
+  // A flat range is one row, so the volume still has somewhere to go.
+  const flat = max === min;
+  const size = flat ? 1 : count;
+  const step = flat ? 0 : (max - min) / size;
+  const rows: ProfileRow[] = [];
+  for (let r = 0; r < size; r++) rows.push({ low: flat ? min : min + r * step, high: flat ? max : r === size - 1 ? max : min + (r + 1) * step, volume: 0, upVolume: 0, downVolume: 0 });
+  const rowOf = (price: number) => (flat ? 0 : Math.min(size - 1, Math.max(0, Math.floor((price - min) / step))));
+
+  let total = 0;
+  for (let i = first; i <= last; i++) {
+    const bar = bars[i];
+    if (!Number.isFinite(bar.high) || !Number.isFinite(bar.low) || !Number.isFinite(bar.volume) || bar.volume <= 0) continue;
+    const from = rowOf(bar.low);
+    const to = rowOf(bar.high);
+    const part = bar.volume / (to - from + 1);
+    const up = bar.close > bar.open ? 1 : bar.close < bar.open ? 0 : 0.5;
+    for (let r = from; r <= to; r++) {
+      rows[r].volume += part;
+      rows[r].upVolume += part * up;
+      rows[r].downVolume += part * (1 - up);
+    }
+    total += bar.volume;
+  }
+  if (total <= 0) return { rows, poc: -1, vah: null, val: null, valueAreaRows: [-1, -1], total: 0 };
+
+  let poc = 0;
+  for (let r = 1; r < size; r++) if (rows[r].volume > rows[poc].volume) poc = r;
+
+  const target = total * share - total * 1e-9;
+  let low = poc;
+  let high = poc;
+  let held = rows[poc].volume;
+  while (held < target && (low > 0 || high < size - 1)) {
+    const above = high < size - 1 ? rows[high + 1].volume : -1;
+    const below = low > 0 ? rows[low - 1].volume : -1;
+    if (above >= below) { high++; held += rows[high].volume; } else { low--; held += rows[low].volume; }
+  }
+  return { rows, poc, vah: rows[high].high, val: rows[low].low, valueAreaRows: [low, high], total };
+}
+
+/** The bar indexes whose timestamps fall in [from, to], as {first, last}; last < first when none do. Bars are in time order. */
+export function indexRangeOfTime(bars: readonly CandleBar[], from: number, to: number): { first: number; last: number } {
+  let first = bars.length;
+  let last = -1;
+  for (let i = 0; i < bars.length; i++) {
+    const t = bars[i].timestamp;
+    if (t >= from && t <= to) {
+      if (first === bars.length) first = i;
+      last = i;
+    }
+  }
+  return { first, last };
+}

package/src/index.ts

@@ -0,0 +1,83 @@
+export { numericWidth, primitiveAttributes } from './attributes.js';
+export type { Change, CursorMark, DiffStatus, PrimitiveAttributes, PrimitiveState, Quality, Side } from './attributes.js';
+export { Notice } from './Notice.js';
+export type { NoticeKind, NoticeProps } from './Notice.js';
+export { useLadderKeys } from './ladder-keys.js';
+export { LADDER_ROW_ATTRIBUTE, nextLadderRow, resolveLadderKey } from './core/ladder-keys.js';
+export type { LadderKeyAction } from './ladder-keys.js';
+export { Transport } from './Transport.js';
+export type { TransportRootProps, TransportSpeedProps } from './Transport.js';
+export { CURSOR_START, Cursor, sameCursor, useCursor } from './Cursor.js';
+export type { CursorBoundary, CursorRootProps, CursorState, CursorValue } from './Cursor.js';
+export { Scrubber, useScrubber } from './Scrubber.js';
+export type { ScrubberMarkProps, ScrubberRootProps, ScrubberThumbProps } from './Scrubber.js';
+export { clampFraction, fractionFromPointer, isActiveScrubPointer, isPrimaryScrubPointer, reduceScrubGesture, resolveScrubKey } from './core/scrubber-gesture.js';
+export type { ScrubGestureEvent, ScrubGestureResult, ScrubKeyAction, ScrubPointer } from './core/scrubber-gesture.js';
+export { DepthProfile } from './DepthProfile.js';
+export type { DepthProfileRootProps } from './DepthProfile.js';
+export { depthGeometry, depthLevelId, nextDepthIndex, resolveDepthKey } from './core/depth-profile.js';
+export type { DepthGeometry, DepthKeyAction, DepthLevel } from './core/depth-profile.js';
+export { DiffTable } from './DiffTable.js';
+export type { DiffTableRootProps } from './DiffTable.js';
+export { DIFF_CHANGE_LABEL, compareExact, diffRowId, holdDiffOrder, nextDiffIndex, nextDiffSort, resolveDiffKey, signedDelta, sortDiffRows } from './core/diff-table.js';
+export type { DiffChange, DiffKeyAction, DiffMove, DiffSort, DiffTableRow } from './core/diff-table.js';
+export { Tape } from './Tape.js';
+export type { TapeRootProps } from './Tape.js';
+export { TAPE_SIDE_LABEL, holdTape, newestFirst, nextTapeIndex, readTape, resolveTapeKey, tapeSummary, tapeTime } from './core/tape.js';
+export type { TapeIssue, TapeKeyAction, TapeMove, TapeRead, TapeRow, TapeSide, TapeTrade } from './core/tape.js';
+export { Ladder } from './Ladder.js';
+export type { LadderRootProps } from './Ladder.js';
+export { buildLadder } from './core/ladder.js';
+export type { LadderBuilt, LadderInput, LadderIssue, LadderLevelIn, LadderRow, LadderSide } from './core/ladder.js';
+export { Receipt } from './Receipt.js';
+export type { ReceiptRootProps } from './Receipt.js';
+export { receiptHash, receiptVerdict, resolveReceiptKey } from './core/receipt-rules.js';
+export type { ReceiptData, ReceiptHashOf, ReceiptVerdict } from './core/receipt-rules.js';
+export { SymbolSearch } from './SymbolSearch.js';
+export type { SymbolSearchRootProps } from './SymbolSearch.js';
+export { buildSymbolIndex, nextSymbolIndex, normalizeSymbolText, resolveSymbolKey, searchSymbols } from './core/symbol-search.js';
+export type { Instrument, MatchHow, MatchedOn, SearchOptions, SymbolIndex, SymbolKeyAction, SymbolMatch } from './core/symbol-search.js';
+export { Chart, useChart } from './Chart.js';
+export { heikinAshi } from './core/candles.js';
+export type { CandleStyle, ChartContext, ChartRootProps, TimeAxisProps } from './Chart.js';
+export { barInterval, chartFrame, clampPriceRange, dataPriceSpan, growViewport, indexOfTime, lastBars, panPriceRange, panViewport, priceTicks, resolveChartKey, tickDecimals, timeOfIndex, zoomPriceRange, zoomViewport } from './core/chart-scale.js';
+export type { CandleBar, ChartFrame, ChartFrameOptions, ChartInclude, PriceSpan, ChartKeyAction, ChartSize, ChartViewport } from './core/chart-scale.js';
+export { Study } from './Studies.js';
+export type { StudyBandProps, StudyLegendProps, StudyLineProps } from './Studies.js';
+export { atr, bollinger, ema, rsi, sma, sourcePrice, studyRange, visibleIndexes, vwap, wma } from './core/studies.js';
+export type { BollingerBands, StudySource, VwapBand, VwapOptions, VwapResult } from './core/studies.js';
+export { VolumeProfile } from './VolumeProfile.js';
+export type { VolumeProfileHistogramProps, VolumeProfileOptionsProps } from './VolumeProfile.js';
+export { indexRangeOfTime, volumeProfile } from './core/volume-profile.js';
+export type { ProfileRow, VolumeProfileOptions, VolumeProfileResult } from './core/volume-profile.js';
+export type { NameProps } from './accessible-name.js';
+export { Toolbar } from './Toolbar.js';
+export type { ToolbarButtonProps, ToolbarRootProps } from './Toolbar.js';
+export { Menu } from './Menu.js';
+export type { MenuItemProps, MenuListProps, MenuRadioItemProps, MenuRootProps, MenuTriggerProps } from './Menu.js';
+export { Submenu } from './Submenu.js';
+export { Drawings, useDrawings } from './Drawings.js';
+export type { DrawingsEditProps, DrawingsListProps, DrawingsLockProps, DrawingsRemoveProps, DrawingsRootProps, DrawingsToolbarProps, DrawingsUndoProps } from './Drawings.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 './core/drawings.js';
+export type { AttachMode, Drawing, DrawingAnchor, DrawingGeometry, DrawingHit, DrawingKeyAction, DrawingTool, SnapMode } from './core/drawings.js';
+export { Selection, Series } from './Selection.js';
+export type { SelectionRootProps, SeriesRootProps } from './SelectionParts.js';
+export { describeSelection, sameSelection, selectionAfterClearTap, selectionAfterEscape, selectionAfterTap } from './core/selection.js';
+export type { ChartSelection, SelectionNames } from './core/selection.js';
+export { CsvDrop } from './CsvDrop.js';
+export type { CsvDropLoad, CsvDropRootProps } from './CsvDrop.js';
+export { describeBarsCsv, parseBarsCsv } from './core/csv-bars.js';
+export type { CsvBarsError, CsvBarsNote, CsvBarsOptions, CsvBarsResult, CsvExtraColumn } from './core/csv-bars.js';
+export { Fullscreen, useFullscreen } from './Fullscreen.js';
+export type { FullscreenFrameProps, FullscreenState, FullscreenToggleProps } from './Fullscreen.js';
+export { FULLSCREEN_LABEL, FULLSCREEN_MESSAGE, resolveFullscreenEscape } from './core/fullscreen.js';
+export type { FullscreenEscape } from './core/fullscreen.js';
+export { Panels, usePanels } from './Panels.js';
+export type { PanelsListProps, PanelsMoveProps, PanelsRootProps } from './PanelsParts.js';
+export type { PanelSeriesData } from './panels-context.js';
+export { AXIS_BOTTOM, MAIN_PANEL, describeMove, moveSeries, moveTargets, normalizeLayout, panelBands, panelOf, reconcileLayout } from './core/panels.js';
+export type { MoveDestination, MoveTarget, PanelBand, PanelLayout, PanelSeriesRequest, PanelSpec } from './core/panels.js';
+
+// The series contract and the adapters (also under ./core): points with a clock, the boundary check, the report, the CSV adapter.
+export { POINT_KINDS, alignSeries, csvAdapter, duplicateIds, pointsFromValues, report, resolveSeries, seriesSetSchema, toSeriesSet, validateSeriesSet } from './core/index.js';
+export type { AdapterIssue, AdapterResult, AlignMode, AlignOptions, AlignedSeries, AlignedState, CsvAdapterOptions, DataAdapter, DataSeries, FindingKind, PointKind, ResolvedSeries, SeriesCalendar, SeriesFinding, SeriesInput, SeriesIssue, SeriesPoint, SeriesSet, SeriesValidation } from './core/index.js';