openalgo-script 0.2.0 → 0.5.0

package/spec/errors.json

@@ -2605,6 +2605,99 @@
       "refines": null,
       "test": "tests/engine/verify.test.ts"
     },
+    {
+      "code": "OS6020",
+      "title": "The report window holds no bars",
+      "severity": "error",
+      "stage": "host",
+      "since": 1,
+      "message": "The window from {from} to {to} holds none of the {count} bars supplied.",
+      "placeholders": {
+        "from": "the first moment the window covers, or the first bar supplied where the host named none",
+        "to": "the last moment it covers",
+        "count": "how many bars were supplied"
+      },
+      "cause": "A report is about the bars inside the window the host chose, and a window holding none of them has nothing to report: no equity point, no trade and no summary. The bars outside it are warmup, which execute and whose orders are real, so an empty window is not an empty run, and reporting one as a flat curve would tell a reader that nothing happened when something did.",
+      "fix": "Widen the window until it covers bars, or supply the bars it covers. Both bounds are inclusive and are compared against the times of the bars supplied rather than against a calendar, so a window that falls inside a gap in the data is empty however wide it looks.",
+      "autofix": false,
+      "example": {
+        "kind": "transcript",
+        "before": "bars supplied: 1240, first day 1, last day 1240\nreport window: day 1300 to day 1400, bars inside 0",
+        "after": "bars supplied: 1240, first day 1, last day 1240\nreport window: day 1100 to day 1240, bars inside 141"
+      },
+      "spec": "language.md 7.1",
+      "refines": null,
+      "test": "tests/backtest/range.test.ts"
+    },
+    {
+      "code": "OS6021",
+      "title": "A run setting cannot be applied as stated",
+      "severity": "error",
+      "stage": "host",
+      "since": 1,
+      "message": "{setting} cannot be applied: {problem}.",
+      "placeholders": {
+        "setting": "the setting that cannot be applied, such as the charge schedule or the comparison tolerance",
+        "problem": "what makes it unusable, such as a charge line levied on a line declared after it"
+      },
+      "cause": "A run states the settings it is carried out under before its first bar, and a setting that cannot be carried out is refused there rather than quietly producing a figure. A charge line levied on lines not declared before it has no single evaluation order, so two engines would charge two different amounts and both would be defensible. A slippage stated in ticks with no tick size to measure a tick in would charge nothing at all, which is a backtest that lies in the strategy's favour. A comparison tolerance carrying a bound and no reason is a failed comparison somebody switched off, and one past the cap conformance.md section 6 puts on a declared tolerance is a comparison the suite will not accept, so a run that declared one is refused a case rather than written into one that fails every runner it meets.",
+      "fix": "State the setting so it can be carried out: declare a charge line after every line it is levied on, supply the tick size a slippage in ticks is measured in, write down the reason a tolerance needs a bound, or bring a bound past the cap back inside it. Nothing has been computed at the point this is refused, so correcting the setting and running again costs one run.",
+      "autofix": false,
+      "example": {
+        "kind": "transcript",
+        "before": "charge lines: tax on levy, levy\nslippage: 2 ticks, tick size not supplied",
+        "after": "charge lines: levy, tax on levy\nslippage: 2 ticks, tick size 0.05"
+      },
+      "spec": "stdlib.md 17.1",
+      "refines": null,
+      "test": "tests/accounting/schedules.test.ts"
+    },
+    {
+      "code": "OS6022",
+      "title": "The bars are not the bars the record was made from",
+      "severity": "error",
+      "stage": "host",
+      "since": 1,
+      "message": "The bars supplied hash to {found}, and the record was made from {expected}.",
+      "placeholders": {
+        "found": "the hash of the bars supplied now",
+        "expected": "the hash the record names"
+      },
+      "cause": "A record names the bars it was made from by a hash over their canonical form, so a replay can prove it is replaying the same run rather than producing a different study under the same name. Bars are revised: a feed corrects a print, a session is extended, a split is applied to history. A replay over revised bars that reported the original figures would be the most convincing wrong answer this system can produce.",
+      "fix": "Replay against the bars the record names. Where the revision is the point, make a second record over the revised bars and compare the two runs, rather than overwriting one run with the other under one name.",
+      "autofix": false,
+      "example": {
+        "kind": "transcript",
+        "before": "record: bars 1240, hash 9f2c4e...\nsupplied: bars 1240, hash 4ab70d...",
+        "after": "record: bars 1240, hash 9f2c4e...\nsupplied: bars 1240, hash 9f2c4e..."
+      },
+      "spec": "conformance.md 3",
+      "refines": null,
+      "test": "tests/backtest/record.test.ts"
+    },
+    {
+      "code": "OS6023",
+      "title": "Two cost models are stated at once",
+      "severity": "error",
+      "stage": "host",
+      "since": 1,
+      "message": "A charge schedule was supplied, and the declaration states a commission of {commission} in {commissionType}.",
+      "placeholders": {
+        "commission": "the commission the declaration states",
+        "commissionType": "the unit that commission is stated in"
+      },
+      "cause": "The declaration's commission is the script's own statement of what trading costs and a supplied schedule is the platform's, and the two describe the same money. Applied together they charge it twice; applied one at a time they charge whichever an engine happened to prefer, which is a rule nobody wrote down and a figure nobody can explain afterwards. So exactly one of the two is stated for a run, and stating both is refused before the first bar rather than reconciled behind the reader.",
+      "fix": "Supply the schedule and leave the declaration's commission at its default of zero, or state the commission in the declaration and supply no schedule. A schedule is the one of the two that can carry a floor, a cap, a charge levied on a charge, and a cost that falls on one side of the trade only.",
+      "autofix": false,
+      "example": {
+        "kind": "transcript",
+        "before": "declaration: commission 20, per trade\nhost: charge schedule supplied, 4 lines",
+        "after": "declaration: commission 0, per trade\nhost: charge schedule supplied, 4 lines"
+      },
+      "spec": "language.md 13.3; stdlib.md 17.1",
+      "refines": null,
+      "test": "tests/backtest/settings.test.ts"
+    },
     {
       "code": "OS7001",
       "title": "Only a strategy can do that",
@@ -2928,7 +3021,7 @@
       "since": 1,
       "message": "This strategy placed an order and the host supplied no destination.",
       "placeholders": {},
-      "cause": "A strategy needs somewhere for orders to go: a paper engine, a backtest simulator or a broker connection. Running one with no destination would compute a position nothing ever took.",
+      "cause": "A strategy needs somewhere for orders to go: a sandbox engine, a backtest simulator or a broker connection. Running one with no destination would compute a position nothing ever took.",
       "fix": "Connect a destination in the host, or run the file as a study(): replace buy() with signal(\"BUY\").",
       "autofix": false,
       "example": {
@@ -2984,6 +3077,53 @@
       "refines": null,
       "test": "tests/engine/closing.test.ts"
     },
+    {
+      "code": "OS7018",
+      "title": "A frame names an order this strategy did not place",
+      "severity": "error",
+      "stage": "host",
+      "since": 1,
+      "message": "The frame names intent {intent}, and this strategy holds no such order.",
+      "placeholders": {
+        "intent": "the intent id the frame named"
+      },
+      "cause": "Step 1 of the fold locates the row a frame is about, and a frame naming no row cannot be folded into anything. It is a fact about the host rather than about the strategy: a destination answering for an order another strategy placed, or answering for a run that has already ended. The frame changes nothing and is reported, because a fold that passed over it in silence would leave a host's mistake invisible to the only party who can correct it.",
+      "fix": "Answer with the intent id the engine sent. A destination's own reference is carried in the frame's reference field, where the engine records it and never parses it, and it is not what an answer is addressed by.",
+      "autofix": false,
+      "example": {
+        "kind": "transcript",
+        "before": "engine sent: intent 7, intent 8\nframe: intent 11, status filled, filled qty 1",
+        "after": "engine sent: intent 7, intent 8\nframe: intent 8, status filled, filled qty 1"
+      },
+      "spec": "stdlib.md 17.8, 17.14",
+      "refines": null,
+      "test": null,
+      "deferred": "Nothing raises this yet. The fold refuses the frame and records the refusal as a word on the outcome it hands back, and a word is not a catalogue code, so nothing reports it against the run and a host answering for orders it was never handed stays invisible. Raised when the outcome of a fold carries a code and a bar carries a channel for a diagnostic that does not stop it, stdlib.md 17.8."
+    },
+    {
+      "code": "OS7019",
+      "title": "A fill was reported with no price",
+      "severity": "error",
+      "stage": "host",
+      "since": 1,
+      "message": "The frame reports {qty} filled for intent {intent}, and no average fill price.",
+      "placeholders": {
+        "qty": "the cumulative filled quantity the frame reports",
+        "intent": "the intent id the frame named"
+      },
+      "cause": "Step 3 of the fold takes the destination's own average over the cumulative quantity, because the engine never averages two averages of its own. A frame reporting more filled than the row holds and no price to take is a fill that can be marked against nothing: no position average, no realised profit, no equity point. It is refused whole rather than folded for its quantity alone, because a position holding a size and no price is worse than no position at all.",
+      "fix": "Report the average fill price the destination computed over the cumulative quantity, on every frame that reports a quantity greater than the last one. A frame carrying no new quantity needs no price.",
+      "autofix": false,
+      "example": {
+        "kind": "transcript",
+        "before": "frame: intent 8, status filled, filled qty 3, average fill price absent",
+        "after": "frame: intent 8, status filled, filled qty 3, average fill price 104.25"
+      },
+      "spec": "stdlib.md 17.8, 17.14",
+      "refines": null,
+      "test": null,
+      "deferred": "Nothing raises this yet. The fold refuses the frame and records the refusal as a word on the outcome it hands back, and a word is not a catalogue code, so a destination reporting a fill that can be marked against nothing is refused in silence. Raised when the outcome of a fold carries a code and a bar carries a channel for a diagnostic that does not stop it, stdlib.md 17.8."
+    },
     {
       "code": "OS8001",
       "title": "A stateful call inside a branch",

package/src/adapters/charts/driving.ts

@@ -0,0 +1,109 @@
+/**
+ * Walking the bars, for a study and for a strategy.
+ *
+ * Split from `run.ts` because they are two things. That file decides what an
+ * engine is loaded with: the host record, the clock, the settings, the venue.
+ * This one decides how the bars are then handed over, and the two differ by
+ * exactly one thing, whether frames have to reach the engine between them.
+ */
+
+import type { CompiledProgram } from '../../core/emit/index.js';
+import type { Engine } from '../../core/engine/index.js';
+import { hostBar, stateFor } from './bars.js';
+import type { ChartBar, ChartCalcContext, ChartSettings } from './contract.js';
+import { stopped } from './errors.js';
+import { signatureOf } from './settings.js';
+import { answersFor } from './venue.js';
+import type { HeldVenue } from './venue.js';
+
+/**
+ * A run in hand, held between a chart's recomputes.
+ *
+ * The signature and the bar times are what a tail run is checked against before
+ * it is trusted: splicing a tail onto a history that has changed underneath it
+ * draws a wrong study that looks entirely plausible.
+ */
+export interface Held {
+  readonly engine: Engine;
+  readonly signature: string;
+  count: number;
+  firstTime: number;
+  lastTime: number;
+  /**
+   * The destination this run's orders go to, for a strategy.
+   *
+   * Held with the engine because the two are one run: the venue holds the
+   * orders that have not filled yet, and an engine continued onto a new bar
+   * against a fresh venue would have its working orders silently forgotten.
+   */
+  readonly venue: HeldVenue | null;
+}
+
+/** A study: every bar in one hand-over, which is what `run` is for. */
+export function runWhole(
+  engine: Engine,
+  bars: readonly ChartBar[],
+  ctx: ChartCalcContext | undefined,
+  program: CompiledProgram,
+  settings: ChartSettings,
+): Held {
+  const result = engine.run(
+    bars.map(hostBar),
+    bars.map((_, index) => stateFor(index, bars, ctx)),
+  );
+  if (result.diagnostic !== undefined) throw stopped(result.diagnostic);
+  return heldFrom(engine, null, bars, program, settings);
+}
+
+/**
+ * A strategy: one bar at a time, with the venue answering between them.
+ *
+ * The order is deliver, execute, then ask. A driver that asked the venue before
+ * executing would price a fill against a bar the strategy had not seen yet, and
+ * one that delivered after executing would let a script read a position its own
+ * order on this bar had just created.
+ *
+ * `supplied` is the whole count rather than the index reached, so `bar.isLast`
+ * means the same on this path as on the one above it: a strategy written to act
+ * on the final bar acts on the final bar, not on every bar in turn.
+ */
+export function walkWith(
+  engine: Engine,
+  held: HeldVenue,
+  bars: readonly ChartBar[],
+  ctx: ChartCalcContext | undefined,
+  program: CompiledProgram,
+  settings: ChartSettings,
+): Held {
+  for (let index = 0; index < bars.length; index += 1) {
+    const bar = bars[index];
+    if (bar === undefined) continue;
+
+    for (const frame of held.pending) engine.deliver(frame);
+    held.pending = [];
+
+    const result = engine.append(hostBar(bar), stateFor(index, bars, ctx), bars.length);
+    if (result.diagnostic !== undefined) throw stopped(result.diagnostic);
+
+    answersFor(held, index);
+  }
+  return heldFrom(engine, held, bars, program, settings);
+}
+
+function heldFrom(
+  engine: Engine,
+  venue: HeldVenue | null,
+  bars: readonly ChartBar[],
+  program: CompiledProgram,
+  settings: ChartSettings,
+): Held {
+  return {
+    engine,
+    venue,
+    signature: signatureOf(program, settings),
+    count: bars.length,
+    firstTime: bars[0]?.time ?? 0,
+    lastTime: bars[bars.length - 1]?.time ?? 0,
+  };
+}
+

package/src/adapters/charts/run.ts

@@ -41,6 +41,11 @@ import type { ChartBar, ChartCalcContext, ChartSettings, ChartStore } from './co
 import { refused, stopped } from './errors.js';
 import { stationIn, stationOf } from './requests.js';
 import { engineSettings, signatureOf } from './settings.js';
+import { answersFor, needsVenue, routeInto, venueFor } from './venue.js';
+import type { HeldVenue } from './venue.js';
+import { runWhole, walkWith } from './driving.js';
+import type { Held } from './driving.js';
+import type { Simulator } from '../../core/backtest/index.js';
 
 /** What a host tells the adapter that neither the chart nor the program says. */
 export interface ChartAdapterOptions {
@@ -116,6 +121,26 @@ export interface ChartAdapterOptions {
    * (`stdlib.md` 17.1), never handed over by the chart.
    */
   readonly orders?: EffectRoute;
+  /**
+   * Run a strategy against a simulated destination where the host gives none.
+   *
+   * **Off by default, because the refusal it replaces is useful.** A strategy
+   * with nowhere to send an order is refused at load with OS6006 naming the
+   * capability, which is exactly what a host that meant to wire a destination
+   * and forgot needs to be told. A chart that quietly filled one in for them
+   * would draw a convincing strategy that routed nothing.
+   *
+   * **On, it is the venue a backtest uses.** A chart drawing a strategy then
+   * fills the same orders at the same prices as the report of the same script,
+   * so the marks on the price and the trades in the report are one answer
+   * rather than two. This is what a host turns on to draw a strategy the way it
+   * draws a study: the plots, the legend row and the settings all follow from
+   * the program running at all.
+   *
+   * It does not place an order anywhere. A host that wants that supplies
+   * `orders`, which wins over this.
+   */
+  readonly simulateOrders?: boolean;
   readonly limits?: Partial<EngineLimits>;
   readonly clock?: Clock;
   /**
@@ -130,14 +155,6 @@ export interface ChartAdapterOptions {
 }
 
 /** The engine one chart instance is holding, between recomputes. */
-interface Held {
-  readonly engine: Engine;
-  readonly signature: string;
-  count: number;
-  firstTime: number;
-  lastTime: number;
-}
-
 /** The store key. Namespaced, because the store belongs to the host as well. */
 const HELD = 'openscript';
 
@@ -168,20 +185,20 @@ export function fullRun(
   options: ChartAdapterOptions,
 ): RunOutput {
   const station = stationIn(store);
-  const engine = start(program, settings, ctx, options, station.provider(bars));
-  const result = engine.run(
-    bars.map(hostBar),
-    bars.map((_, index) => stateFor(index, bars, ctx)),
-  );
-  if (result.diagnostic !== undefined) throw stopped(result.diagnostic);
+  const started = start(program, settings, ctx, options, station.provider(bars), bars);
+  const engine = started.engine;
 
-  const held: Held = {
-    engine,
-    signature: signatureOf(program, settings),
-    count: bars.length,
-    firstTime: bars[0]?.time ?? 0,
-    lastTime: bars[bars.length - 1]?.time ?? 0,
-  };
+  // **A strategy is walked bar by bar and a study is handed the lot.** The
+  // difference is the venue: its frames reach the engine between bars, which is
+  // the only place they can, so a strategy's position is right on the bar after
+  // the one it traded on. `run()` has no gap to put them in.
+  //
+  // It is also the loop the backtest uses, which is the point: a chart drawing a
+  // strategy and a report of the same strategy walk the same bars in the same
+  // order against the same venue, so they cannot disagree about what filled.
+  const held: Held = started.venue === null
+    ? runWhole(engine, bars, ctx, program, settings)
+    : walkWith(engine, started.venue, bars, ctx, program, settings);
   store[HELD] = held;
   station.settle();
   return outputOf(program, engine);
@@ -218,11 +235,29 @@ export function tailRun(
     const bar = bars[index];
     if (bar === undefined) return null;
     const state = stateFor(index, bars, ctx);
+
+    // The venue's answers about the bar before this one, delivered before this
+    // one runs, exactly as the full walk does. A tail that skipped this would
+    // draw the first bars of a strategy correctly and then quietly stop folding
+    // its fills the moment the chart went live, which is the half of the run
+    // nobody re-checks.
+    //
+    // Only when the bar is new. Re-executing the bar that moved must not
+    // deliver again: a frame is cumulative and folding one twice is harmless,
+    // but the bar's own orders have been rolled back and answering them a
+    // second time would fill an order the engine no longer knows it sent.
+    if (held.venue !== null && index !== from) {
+      for (const frame of held.venue.pending) held.engine.deliver(frame);
+      held.venue.pending = [];
+    }
+
     const result =
       index === from
         ? held.engine.update(hostBar(bar), state)
         : held.engine.append(hostBar(bar), state);
     if (result.diagnostic !== undefined) throw stopped(result.diagnostic);
+
+    if (held.venue !== null) answersFor(held.venue, index);
   }
 
   held.count = bars.length;
@@ -257,23 +292,65 @@ function outputOf(program: CompiledProgram, engine: Engine): RunOutput {
   return { columns, tables: engine.tables(), drawings: engine.drawings() };
 }
 
+/** A loaded engine, and the destination its orders go to where it has one. */
+interface Started {
+  readonly engine: Engine;
+  readonly venue: HeldVenue | null;
+}
+
+/**
+ * Load the program, and give a strategy somewhere for its orders to go.
+ *
+ * **The venue is built after the load and reached through a holder, because
+ * neither can come first.** The route has to be handed to `load`, since that is
+ * what declares the `orders` capability and a program needing one is otherwise
+ * refused. The venue has to be built after it, because the declaration it reads
+ * may state its fill rule through an `input()`, and inputs are not resolved
+ * until `load` has run. The route is only ever called from inside an execution,
+ * which is after both, so the holder is always filled by the time anything
+ * reaches it.
+ *
+ * **A host that supplied its own route keeps it.** Somewhere real to send an
+ * order is a better destination than a simulated one, and a host that wired one
+ * up meant it.
+ *
+ * **And simulation is asked for rather than assumed.** Without
+ * `simulateOrders` a strategy with nowhere to send an order is still refused at
+ * load, which is the answer a host that meant to wire a destination and forgot
+ * needs to see. Filling in a venue for them would turn that mistake into a
+ * chart that draws convincingly and routes nothing, discovered whenever
+ * somebody next looked for the orders.
+ */
 function start(
   program: CompiledProgram,
   settings: ChartSettings,
   ctx: ChartCalcContext | undefined,
   options: ChartAdapterOptions,
   requests: RequestProvider,
-): Engine {
+  bars: readonly ChartBar[],
+): Started {
+  const holder: { current: Simulator | null } = { current: null };
+  const simulate = options.simulateOrders === true && options.orders === undefined && needsVenue(program);
+  const withRoute: ChartAdapterOptions = simulate
+    ? { ...options, orders: routeInto(holder) }
+    : options;
+
   const loaded = load(program, {
     settings: engineSettings(program, settings),
-    host: hostFor(ctx, options, requests),
+    host: hostFor(ctx, withRoute, requests),
     time: timeFor(options, ctx?.timezone ?? ''),
     ...(options.limits === undefined ? {} : { limits: options.limits }),
     ...(options.source === undefined ? {} : { source: options.source }),
     ...(options.clock === undefined ? {} : { clock: options.clock }),
   });
   if (!loaded.ok) throw refused(loaded.diagnostic);
-  return loaded.engine;
+
+  if (!simulate) return { engine: loaded.engine, venue: null };
+
+  const venue = venueFor(program, bars, loaded.inputs, instrumentFor(ctx, options));
+  if (venue === null) return { engine: loaded.engine, venue: null };
+  holder.current = venue;
+  return { engine: loaded.engine, venue: { venue, pending: [] } };
 }
 
 /**
@@ -286,12 +363,19 @@ function start(
  * the chart's own sentence in `req.error`, instead of being refused at load
  * with OS6006 naming a capability the chart does have.
  */
-function hostFor(
+/**
+ * The instrument record, from what the host stated and what the chart knows.
+ *
+ * Its own function because two callers need it and they must not each build
+ * one: the engine is loaded with this record, and the venue prices fills
+ * against the tick size in it. Two spellings of the same record is how a fill
+ * gets rounded to a tick the strategy was never told about.
+ */
+function instrumentFor(
   ctx: ChartCalcContext | undefined,
   options: ChartAdapterOptions,
-  requests: RequestProvider,
-): EngineHost {
-  const instrument: Instrument = {
+): Instrument {
+  return {
     ...(options.instrument ?? {}),
     ...(ctx?.symbol === undefined ? {} : { symbol: ctx.symbol }),
     ...(ctx?.interval === undefined ? {} : { interval: ctx.interval }),
@@ -302,6 +386,14 @@ function hostFor(
     // the chart it was drawn on.
     ...(ctx === undefined || ctx.timezone === '' ? {} : { timezone: ctx.timezone }),
   };
+}
+
+function hostFor(
+  ctx: ChartCalcContext | undefined,
+  options: ChartAdapterOptions,
+  requests: RequestProvider,
+): EngineHost {
+  const instrument = instrumentFor(ctx, options);
   return {
     instrument,
     requestBars: requests,

package/src/adapters/charts/surfaces.ts

@@ -100,6 +100,23 @@ export interface ChartTableOptions {
   readonly borderWidth: number;
   /** The backdrop behind the whole grid, which is the grid's own `bgColor`. */
   readonly background?: string;
+  /**
+   * Column widths in media pixels, one per column.
+   *
+   * The chart's own default is one flat width for every column, which is a
+   * width chosen without seeing the text. A grid whose first column says
+   * "Moving averages" and whose second says "RSI: 27.22" has two columns that
+   * want different room, and one number cannot give it to both.
+   */
+  readonly cellWidth?: readonly number[];
+  /**
+   * `'auto'` to shrink a cell's type until its text fits the cell it is in.
+   *
+   * The chart measures the text it is about to draw, which nothing upstream of
+   * it can do, so this is what makes a column width that is slightly wrong
+   * merely slightly loose instead of two cells written over each other.
+   */
+  readonly fontSize?: number | 'auto';
 }
 
 /** A grid of cells pinned to a corner, and the options it is drawn with. */

package/src/adapters/charts/tables.ts

@@ -118,10 +118,98 @@ function oneTable(
       position: CORNERS[position] ?? 'top-right',
       borderWidth: numberField(declared.options.borderWidth, lookup, 0),
       ...(bgColour === undefined ? {} : { background: cssColour(bgColour) }),
+      ...(cols > 0 ? { cellWidth: columnWidths(grid, cols) } : {}),
+      // The chart measures the text it is about to draw and shrinks it to fit,
+      // which is the half of this that cannot be done from here.
+      fontSize: 'auto',
     },
   };
 }
 
+/**
+ * How wide each column has to be, in media pixels.
+ *
+ * The chart's default is one width for every column, chosen without seeing the
+ * text, and a grid whose header says "Moving averages" over cells saying
+ * "RSI: 27.22" has one column bleeding into the next. Nothing downstream can
+ * choose better, because by the time the chart has the grid it has lost which
+ * cells belong together; and nothing upstream can, because the script declares
+ * a size and writes text, not a layout.
+ *
+ * **This is an estimate, and it is allowed to be.** A real width needs the font
+ * the chart will draw with, and only the chart has it. So the width is counted
+ * off the characters and the chart's own `fontSize: 'auto'` corrects whatever
+ * this gets wrong: too narrow and the type shrinks a little, too wide and the
+ * column is a little loose. Either is a table that reads. The failure this
+ * replaces was neither.
+ *
+ * Delete it when the chart can size a column from its own measurements. It
+ * exists because that is not a thing it can be asked to do yet.
+ */
+function columnWidths(grid: readonly (readonly ChartCell[])[], cols: number): number[] {
+  const widths: number[] = [];
+  for (let col = 0; col < cols; col += 1) {
+    let widest = 0;
+    for (const row of grid) {
+      const text = row[col]?.text ?? '';
+      if (text.length > 0) widest = Math.max(widest, textWidth(text));
+    }
+    widths.push(Math.min(MAX_COLUMN, Math.max(MIN_COLUMN, Math.ceil(widest) + CELL_PADDING * 2)));
+  }
+  return widths;
+}
+
+/**
+ * Roughly how wide a string is at the type size the chart starts from.
+ *
+ * Counted rather than measured, and counted in two weights rather than one: a
+ * column of "Histogram: -7.01" is half punctuation and narrow digits, and
+ * treating every character as an em-and-a-bit makes that column half again as
+ * wide as it needs to be while "Moving averages" stays too narrow. Two weights
+ * is not typography, but it is enough to tell those two apart.
+ */
+function textWidth(text: string): number {
+  let width = 0;
+  for (const character of text) {
+    width += NARROW.has(character) ? BASE_SIZE * NARROW_EM : BASE_SIZE * WIDE_EM;
+  }
+  return width;
+}
+
+/** The characters that take noticeably less than an average advance. */
+const NARROW = new Set([...' .,:;!|ijlt1IJfr()[]{}-']);
+
+/**
+ * The type size the widths are counted at.
+ *
+ * The chart's own default row is 18 media pixels and it draws at 62% of the
+ * row, so this is the size a cell gets before anything shrinks it. Counting at
+ * a larger size would reserve room the text never uses.
+ */
+const BASE_SIZE = 11;
+const NARROW_EM = 0.32;
+const WIDE_EM = 0.56;
+
+/** What the chart insets a cell's text by, on each side. */
+const CELL_PADDING = 4;
+
+/**
+ * The narrowest a column is drawn.
+ *
+ * A column of one-character cells sized to its content is a sliver, and a grid
+ * of slivers reads as a rendering fault rather than as a narrow column.
+ */
+const MIN_COLUMN = 56;
+
+/**
+ * The widest a column is drawn.
+ *
+ * A cell holding a sentence would otherwise push the grid past the pane it is
+ * pinned inside, taking the chart with it. Past this the type shrinks instead,
+ * which is the chart's job and it is better at it.
+ */
+const MAX_COLUMN = 220;
+
 /**
  * One written cell, or none.
  *