openalgo-script 0.7.2 → 0.8.0

package/src/adapters/charts/capabilities.ts

@@ -0,0 +1,103 @@
+/**
+ * What the host's chart can draw, read from the version the host states.
+ *
+ * The adapter declares the descriptor's shape rather than importing the chart
+ * library, for the reason `contract.ts` gives, so it cannot ask the library
+ * what it has. Two hooks arrived after the oldest chart the peer range accepts:
+ * a band's per-bar colour callback and the list of grids, both in 2.5.4. A
+ * chart ignores a hook it does not know, so a descriptor that relied on either
+ * would draw, on an older chart, a band in the chart's own default colours or
+ * the first grid alone, and say nothing. That is the failure OS6024 exists to
+ * end, so where the adapter cannot tell, it refuses (`undrawable.ts`).
+ *
+ * **The host states the version, and the adapter reads what that version
+ * has.** The library exports its own version string, and a host that imports
+ * the chart already holds it: `descriptorFor(program, { chartVersion: VERSION })`.
+ * A version rather than a switch per hook, because a switch is a fact about the
+ * chart that the host has to look up and keep true through every upgrade and
+ * downgrade, while the version is the chart it actually installed.
+ *
+ * **Nothing stated reads as the oldest chart**, which is the descriptor every
+ * host got before the option existed: nothing it draws changes, and a program
+ * that needs either hook is refused as it was. A string that is not a version
+ * reads the same way, and the refusal says the string could not be read rather
+ * than guessing at what it meant. A prerelease orders before its release, as
+ * version precedence orders it, so `2.5.4-rc.1` reads as a chart without what
+ * 2.5.4 added; build metadata after a `+` orders nothing and is ignored.
+ */
+
+/** What the chart this descriptor is registered with will read. */
+export interface ChartCapabilities {
+  /** A band's colour per bar, through the band's own colour callback. */
+  readonly bandColours: boolean;
+  /** Every declared grid, through the list of grids with an id each. */
+  readonly grids: boolean;
+  /** What the host stated, for the sentence a refusal carries. */
+  readonly stated: string | undefined;
+}
+
+/** The two hooks this reads a version for. */
+export type Capability = 'bandColours' | 'grids';
+
+/** The chart version each hook arrived in. */
+const SINCE: Readonly<Record<Capability, string>> = {
+  bandColours: '2.5.4',
+  grids: '2.5.4',
+};
+
+/** `major.minor.patch`, an optional prerelease, optional build metadata. */
+const VERSION = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(-[0-9A-Za-z.-]+)?(\+[0-9A-Za-z.-]+)?$/;
+
+interface Read {
+  readonly release: readonly [number, number, number];
+  readonly prerelease: boolean;
+}
+
+export function capabilitiesOf(stated: string | undefined): ChartCapabilities {
+  const read = stated === undefined ? undefined : readVersion(stated);
+  return {
+    bandColours: read !== undefined && reaches(read, SINCE.bandColours),
+    grids: read !== undefined && reaches(read, SINCE.grids),
+    stated,
+  };
+}
+
+/**
+ * The sentence a refusal gives for a hook the chart may not have.
+ *
+ * `older` is what a chart without the hook does, in the words a reader of the
+ * refusal needs; the rest says which version has it and what this host stated,
+ * because the fix is the host's and it has to know which of the two to change.
+ */
+export function lacking(chart: ChartCapabilities, capability: Capability, older: string): string {
+  const since = SINCE[capability];
+  const stated = chart.stated;
+  const which =
+    stated === undefined
+      ? 'this host stated no chart version'
+      : readVersion(stated) === undefined
+        ? `this host stated ${JSON.stringify(stated)}, which is not a version this adapter can read`
+        : `this host stated version ${stated}`;
+  return `${older} before chart version ${since}, and ${which}`;
+}
+
+function readVersion(text: string): Read | undefined {
+  const match = VERSION.exec(text);
+  if (match === null) return undefined;
+  return {
+    release: [Number(match[1]), Number(match[2]), Number(match[3])],
+    prerelease: match[4] !== undefined,
+  };
+}
+
+/** Whether a stated version is at or past the one a hook arrived in. */
+function reaches(read: Read, since: string): boolean {
+  const needed = readVersion(since);
+  if (needed === undefined) return false;
+  for (let part = 0; part < 3; part += 1) {
+    const have = read.release[part] ?? 0;
+    const need = needed.release[part] ?? 0;
+    if (have !== need) return have > need;
+  }
+  return !read.prerelease;
+}

package/src/adapters/charts/columns.ts

@@ -42,6 +42,11 @@ export function levelKey(index: number): string {
   return `openscript:level:${index}`;
 }
 
+/** The key one side of a band's computed colour travels under. */
+export function bandColourKey(band: number, side: 'up' | 'down'): string {
+  return `openscript:fill:${band}:${side}`;
+}
+
 /** The two keys a per-bar colour travels under. */
 export function colourKeys(key: string): { readonly rgb: string; readonly alpha: string } {
   return { rgb: `${key}:rgb`, alpha: `${key}:alpha` };

package/src/adapters/charts/contract.ts

@@ -32,7 +32,7 @@
  * What is declared is the whole output surface: the inputs and the settings
  * dialog a chart generates from them, the plots with their styles and scales,
  * the bands between them, the horizontal levels, the pane's fixed range, the
- * markers, the candle and pane painting, the summary grid, the drawing objects,
+ * markers, the candle and pane painting, the summary grids, the drawing objects,
  * the watched conditions, and the lifecycle a read of another instrument fetches
  * through.
  *
@@ -56,6 +56,7 @@ import type {
   ChartGrid,
   ChartMarker,
   ChartSurfaceContext,
+  ChartTableSpec,
 } from './surfaces.js';
 
 /** One bar as the chart holds it. Its time is UTC seconds, not milliseconds. */
@@ -223,6 +224,20 @@ export interface ChartPlot {
   colorParts?(ctx: ChartColorContext): ChartBarColor | undefined;
 }
 
+/**
+ * What a band's per-bar colour callback is handed, for one bar.
+ *
+ * `a` and `b` are the two columns the band is drawn between, read on that bar,
+ * and `null` where either has no value, which is a bar the band is not drawn on.
+ */
+export interface ChartFillContext {
+  readonly index: number;
+  readonly a: number | null;
+  readonly b: number | null;
+  readonly values: ChartValues;
+  readonly settings: ChartSettings;
+}
+
 export interface ChartFill {
   readonly between: readonly [string, string];
   readonly colorUp?: string;
@@ -231,6 +246,15 @@ export interface ChartFill {
   readonly colorDownKey?: string;
   readonly opacity?: number;
   readonly overlay?: boolean;
+  /**
+   * The band's colour on one bar, for a band whose colour the script computes.
+   *
+   * Present only on such a band, and only where the host states a chart that
+   * has the callback (`capabilities.ts`). Nothing where that bar's side is not
+   * computed per bar, which leaves the chart drawing the band's own colour for
+   * that side.
+   */
+  colorBy?(ctx: ChartFillContext): string | undefined;
 }
 
 export interface ChartLevel {
@@ -305,8 +329,18 @@ export interface ChartDescriptor {
   background?(ctx: ChartSurfaceContext): readonly (string | null)[];
   /** Every marker the last calculation produced, oldest bar first. */
   markers?(ctx: ChartSurfaceContext): readonly ChartMarker[];
-  /** The declared grid as the last executed bar left it, or nothing. */
+  /** The first declared grid as the last executed bar left it, or nothing. */
   table?(ctx: ChartSurfaceContext): ChartGrid | null;
+  /**
+   * Every declared grid as the last executed bar left it, each under its
+   * declaration's key.
+   *
+   * A chart that has this hook reads it in place of `table`, and one that does
+   * not reads `table` and draws the first grid. So it is present only where the
+   * host states a chart that has it (`capabilities.ts`), and a second grid is
+   * refused on a chart that does not.
+   */
+  tables?(ctx: ChartSurfaceContext): readonly ChartTableSpec[];
   /** Every drawing object the script currently holds, oldest first. */
   draws?(ctx: ChartSurfaceContext): readonly ChartDrawing[];
   /**

package/src/adapters/charts/descriptor.ts

@@ -14,7 +14,7 @@
  * second thing to keep in step with the specification.
  *
  * **The hooks that follow a calculation read it and do not repeat it.** Markers,
- * the grid, the drawing objects and each alert's message channel are taken once,
+ * the grids, the drawing objects and each alert's message channel are taken once,
  * while the engine is in hand, and left in the run record `produced.ts` keeps.
  * The chart calls each hook after every calculation, so asking twice gives one
  * answer and a study with a grid costs the same over a hundred thousand bars as
@@ -43,6 +43,7 @@
  */
 import type { CompiledProgram } from '../../core/emit/index.js';
 import { alertMessages, buildAlerts } from './alerts.js';
+import { capabilitiesOf } from './capabilities.js';
 import { valuesFrom } from './columns.js';
 import type {
   ChartBar,
@@ -70,8 +71,9 @@ import type {
   ChartGrid,
   ChartMarker,
   ChartSurfaceContext,
+  ChartTableSpec,
 } from './surfaces.js';
-import { buildTable } from './tables.js';
+import { buildTables, firstGrid } from './tables.js';
 
 /** The grey an unnamed marker is drawn in, where the host names no default. */
 const MARKER_COLOUR = 'rgba(128, 128, 128, 1)';
@@ -87,11 +89,14 @@ export function descriptorFor(
   // afterwards carry a settings key instead of a value, and the two that cannot
   // are read again per call: a level's style and the pane's range.
   const declared = lookupFor(program, options.settings ?? {});
+  // Which of the descriptor's newer hooks the host's chart reads. A hook it may
+  // not read is left off, and what needs one is refused before a bar runs.
+  const chart = capabilitiesOf(options.chartVersion);
 
   const overlay = boolField(program.meta.overlay, declared) === true;
   const plots = buildPlots(program, declared, !overlay);
   const levels = buildLevels(program);
-  const fills = buildFills(program, declared);
+  const fills = buildFills(program, declared, chart);
   const paint = buildPaint(program);
   const alerts = buildAlerts(program, declared);
   const columns = [
@@ -99,6 +104,7 @@ export function descriptorFor(
     ...levels.columns,
     ...paint.columns,
     ...alerts.columns,
+    ...fills.columns,
   ];
   const markerColour = options.markerColor ?? MARKER_COLOUR;
 
@@ -117,7 +123,7 @@ export function descriptorFor(
     const lookup = lookupFor(program, settings);
     remember(settings, {
       markers: buildMarkers(program, lookup, bars, ran.columns, markerColour),
-      table: buildTable(program, lookup, ran.tables),
+      tables: buildTables(program, lookup, ran.tables),
       drawings: buildDrawings(ran.drawings),
       messages: alertMessages(program, ran.columns),
     });
@@ -134,7 +140,7 @@ export function descriptorFor(
     placement: overlay ? 'onchart' : 'pane',
     inputs: inputRows(program),
     plots: plots.plots,
-    ...(fills.length === 0 ? {} : { fills }),
+    ...(fills.fills.length === 0 ? {} : { fills: fills.fills }),
 
     ...(alerts.alerts.length === 0 ? {} : { alerts: alerts.alerts }),
 
@@ -175,7 +181,16 @@ export function descriptorFor(
         }),
     ...(program.outputs.tables.length === 0
       ? {}
-      : { table: (ctx: ChartSurfaceContext): ChartGrid | null => producedFor(ctx.settings).table }),
+      : {
+          table: (ctx: ChartSurfaceContext): ChartGrid | null =>
+            firstGrid(producedFor(ctx.settings).tables),
+        }),
+    ...(program.outputs.tables.length === 0 || !chart.grids
+      ? {}
+      : {
+          tables: (ctx: ChartSurfaceContext): readonly ChartTableSpec[] =>
+            producedFor(ctx.settings).tables,
+        }),
     ...(program.requires.includes('objects')
       ? {
           draws: (ctx: ChartSurfaceContext): readonly ChartDrawing[] =>

package/src/adapters/charts/fills.ts

@@ -2,23 +2,40 @@
  * Declared bands into the chart's shaded bands.
  *
  * A band is two plot keys and two colours, which is the chart's own spec, so the
- * pair of keys crosses unchanged. Two details do not.
+ * pair of keys crosses unchanged. Three details do not.
  *
  * **Opacity is a dimmer, not a second alpha.** A colour carries its own alpha
  * everywhere in the language, and the band's `opacity` multiplies whatever the
- * colours already are. That is exactly what the chart does with the field, so a
- * script that never touches it gets the colour it wrote.
+ * colours already are. That is exactly what the chart does with the field, to a
+ * colour computed per bar as much as to a constant one, so a script that never
+ * touches it gets the colour it wrote.
  *
  * **A band with no colour of its own follows the first plot.** `stdlib.md` 14.2
  * says such a band is that plot's colour faded to twelve percent, and the plot's
  * colour may be one the host picked from its palette rather than one the script
  * wrote, so the band is pointed at the plot's settings key rather than at a value
  * read now. The twelve percent is then the dimmer, multiplied by whatever the
- * script asked for.
+ * script asked for. A band whose colour is computed per bar has a colour of its
+ * own, so neither applies to it.
+ *
+ * **A colour computed per bar travels as columns and is read back per bar.**
+ * It arrives on a channel, rides the values table as the two columns
+ * `columns.ts` describes, and the band's colour callback reads them on each bar
+ * for the side the band is on there. The side is decided the way the chart
+ * decides it, the first plot at or above the second, so the colour answered is
+ * the colour of the run the chart is drawing that bar in. An absent colour is a
+ * transparent one rather than no answer, because no answer hands the bar to
+ * the band's colour for that side, and `docs/visuals/fills.md` teaches an absent
+ * colour as how a band switches itself off. The callback exists only on a chart
+ * that reads it (`capabilities.ts`); on any other, `undrawable.ts` has refused
+ * the program before this is drawn.
  */
 import type { Band, CompiledProgram } from '../../core/emit/index.js';
+import type { ChartCapabilities } from './capabilities.js';
 import { cssColour } from './colours.js';
-import type { ChartFill } from './contract.js';
+import { bandColourKey, colourAt, colourColumns } from './columns.js';
+import type { ColumnSpec } from './columns.js';
+import type { ChartFill, ChartFillContext } from './contract.js';
 import { boolField, colourField, isReference, numberField } from './fields.js';
 import type { InputLookup } from './fields.js';
 
@@ -30,17 +47,67 @@ import type { InputLookup } from './fields.js';
  */
 const UNCOLOURED_FADE = 0.12;
 
-export function buildFills(program: CompiledProgram, lookup: InputLookup): readonly ChartFill[] {
-  const out: ChartFill[] = [];
-  for (const band of program.outputs.fills) out.push(oneBand(program, band, lookup));
-  return out;
+/** What a bar whose computed colour is absent is painted in: nothing. */
+const UNPAINTED = 'rgba(0, 0, 0, 0)';
+
+export interface FillsBuild {
+  readonly fills: readonly ChartFill[];
+  /** The colour columns the bands' callbacks read, for the values table. */
+  readonly columns: readonly ColumnSpec[];
 }
 
-function oneBand(program: CompiledProgram, band: Band, lookup: InputLookup): ChartFill {
+export function buildFills(
+  program: CompiledProgram,
+  lookup: InputLookup,
+  chart: ChartCapabilities,
+): FillsBuild {
+  const fills: ChartFill[] = [];
+  const columns: ColumnSpec[] = [];
+  program.outputs.fills.forEach((band, index) => {
+    const perBar = chart.bandColours ? perBarColours(band, index) : undefined;
+    if (perBar !== undefined) columns.push(...perBar.columns);
+    fills.push(oneBand(program, band, lookup, perBar));
+  });
+  return { fills, columns };
+}
+
+/** The keys a band's two computed colours travel under, and their columns. */
+interface PerBar {
+  readonly up: string | undefined;
+  readonly down: string | undefined;
+  readonly columns: readonly ColumnSpec[];
+}
+
+/**
+ * The columns a band's computed colours need, or nothing for a band with none.
+ *
+ * `color = ...` computed per bar writes one channel into both sides, and that
+ * channel travels once rather than twice.
+ */
+function perBarColours(band: Band, index: number): PerBar | undefined {
+  const upChannel = band.colorUpChannel;
+  const downChannel = band.colorDownChannel;
+  if (upChannel === null && downChannel === null) return undefined;
+  const up = upChannel === null ? undefined : bandColourKey(index, 'up');
+  const shared = downChannel !== null && downChannel === upChannel;
+  const down = downChannel === null ? undefined : shared ? up : bandColourKey(index, 'down');
+  const columns: ColumnSpec[] = [];
+  if (up !== undefined && upChannel !== null) columns.push(...colourColumns(up, upChannel));
+  if (down !== undefined && downChannel !== null && !shared) columns.push(...colourColumns(down, downChannel));
+  return { up, down, columns };
+}
+
+function oneBand(
+  program: CompiledProgram,
+  band: Band,
+  lookup: InputLookup,
+  perBar: PerBar | undefined,
+): ChartFill {
   const up = colourField(band.colorUp, lookup);
   const down = colourField(band.colorDown, lookup);
   const overlay = boolField(band.overlay, lookup);
-  const declared = up !== undefined || down !== undefined;
+  const computed = band.colorUpChannel !== null || band.colorDownChannel !== null;
+  const declared = up !== undefined || down !== undefined || computed;
   const opacity = numberField(band.opacity, lookup, 1) * (declared ? 1 : UNCOLOURED_FADE);
   const follow = declared ? undefined : plotColourKey(program, band.between[0]);
 
@@ -53,6 +120,23 @@ function oneBand(program: CompiledProgram, band: Band, lookup: InputLookup): Cha
     ...(follow === undefined ? {} : { colorUpKey: follow, colorDownKey: follow }),
     opacity,
     ...(overlay === undefined ? {} : { overlay }),
+    ...(perBar === undefined ? {} : { colorBy: colourBy(perBar) }),
+  };
+}
+
+/**
+ * The band's colour on one bar: the computed colour for the side it is on.
+ *
+ * Nothing where either column is absent, which is a bar the chart does not
+ * draw, and nothing where that side's colour is not computed, which leaves the
+ * chart the band's own colour for the side.
+ */
+function colourBy(perBar: PerBar): (ctx: ChartFillContext) => string | undefined {
+  return (ctx: ChartFillContext): string | undefined => {
+    if (typeof ctx.a !== 'number' || typeof ctx.b !== 'number') return undefined;
+    const key = ctx.a >= ctx.b ? perBar.up : perBar.down;
+    if (key === undefined) return undefined;
+    return colourAt(ctx.values, ctx.index, key) ?? UNPAINTED;
   };
 }
 

package/src/adapters/charts/index.ts

@@ -16,10 +16,16 @@
  * What is mapped is the whole output surface: the declared inputs and the
  * settings dialog a chart generates from them, the plots with their styles and
  * scales, the bands between them, the horizontal levels, the pane's fixed range,
- * the markers, the candle and pane painting, the summary grid, the drawing
+ * the markers, the candle and pane painting, the summary grids, the drawing
  * objects a script mutates over time, the watched conditions, and the lifecycle
  * a read of another instrument fetches through.
  *
+ * **Two of those depend on the chart the host states.** A band coloured per bar
+ * and a study with more than one grid need hooks only a newer chart has, so a
+ * host passes the chart library's own `VERSION` as
+ * `ChartAdapterOptions.chartVersion`, and without it such a study is refused
+ * with OS6024 rather than drawn in part. `capabilities.ts` has the versions.
+ *
  * What a study can express and this descriptor has no field for is recorded,
  * with its reason, in `spec/chart-narrowings.json`, and each one is also named
  * in the file that would have written it. `scripts/check-chart-surface.mjs`
@@ -41,6 +47,7 @@ export type {
   ChartCalcContext,
   ChartDescriptor,
   ChartFill,
+  ChartFillContext,
   ChartInput,
   ChartLevel,
   ChartLevelContext,
@@ -75,4 +82,5 @@ export type {
   ChartSurfaceContext,
   ChartTableOptions,
   ChartTablePosition,
+  ChartTableSpec,
 } from './surfaces.js';

package/src/adapters/charts/produced.ts

@@ -32,7 +32,7 @@
  */
 import type { Value } from '../../core/engine/index.js';
 import type { ChartSettings } from './contract.js';
-import type { ChartDrawing, ChartGrid, ChartMarker } from './surfaces.js';
+import type { ChartDrawing, ChartMarker, ChartTableSpec } from './surfaces.js';
 
 /**
  * One declared alert's message channel, whole, as the run left it.
@@ -47,13 +47,14 @@ export type MessageColumn = readonly Value[];
 /** One run's non-numeric output, as the hooks that follow it read it. */
 export interface Produced {
   readonly markers: readonly ChartMarker[];
-  readonly table: ChartGrid | null;
+  /** Every declared grid, in declaration order; the single hook reads the first. */
+  readonly tables: readonly ChartTableSpec[];
   readonly drawings: readonly ChartDrawing[];
   /** One entry per declared alert, in the order `outputs.alerts` declares them. */
   readonly messages: readonly MessageColumn[];
 }
 
-const NOTHING: Produced = { markers: [], table: null, drawings: [], messages: [] };
+const NOTHING: Produced = { markers: [], tables: [], drawings: [], messages: [] };
 
 const runs = new WeakMap<ChartSettings, Produced>();
 

package/src/adapters/charts/run.ts

@@ -38,6 +38,7 @@ import type { CompiledProgram } from '../../core/emit/index.js';
 import type { SourceFile } from '../../core/index.js';
 import { hostBar, hostNow, stateFor } from './bars.js';
 import type { ChartBar, ChartCalcContext, ChartSettings, ChartStore } from './contract.js';
+import { capabilitiesOf } from './capabilities.js';
 import { refused, stopped } from './errors.js';
 import { undrawable } from './undrawable.js';
 import { stationIn, stationOf } from './requests.js';
@@ -60,6 +61,29 @@ export interface ChartAdapterOptions {
   readonly id?: string;
   /** The category a picker groups the study under, when `meta.group` is empty. */
   readonly category?: string;
+  /**
+   * The chart library's own version: the `VERSION` string it exports, which a
+   * host that imports the chart already holds, passed on as
+   * `descriptorFor(program, { chartVersion: VERSION })`.
+   *
+   * It says which of the descriptor's hooks the chart this descriptor is
+   * registered with will read. Two arrived after the oldest chart the peer
+   * range accepts: a band's per-bar colour and the list of grids. From 2.5.4
+   * on, a band whose colour the script computes is drawn bar by bar and every
+   * declared grid is drawn. Before it, or when nothing is stated, the adapter
+   * cannot tell whether the chart will read either hook, and a chart that
+   * ignores one draws a band in its own default colours or the first grid
+   * alone, with nothing said. So such a program is refused before any bar runs
+   * with OS6024, which is what a host that states nothing got before this
+   * option existed.
+   *
+   * The version rather than a switch per hook, because it is one fact the
+   * host already holds, it moves with the chart the host actually installed,
+   * and a hook the adapter learns to read later needs nothing new from any
+   * host. `capabilities.ts` has the rule, prereleases and unreadable strings
+   * included.
+   */
+  readonly chartVersion?: string;
   /**
    * What the host has stored for this study's inputs, for the declared shape.
    *
@@ -338,7 +362,7 @@ function start(
 
   // What this chart has no room for is refused before the engine is asked,
   // because a study drawn without it is a study that looks broken.
-  const narrower = undrawable(program);
+  const narrower = undrawable(program, capabilitiesOf(options.chartVersion));
   if (narrower !== undefined) throw refused(narrower);
 
   const loaded = load(program, {

package/src/adapters/charts/surfaces.ts

@@ -125,6 +125,18 @@ export interface ChartGrid {
   readonly options?: ChartTableOptions;
 }
 
+/**
+ * One grid of several, under an identity the chart keeps it by.
+ *
+ * The chart reuses the grid a recompute names again and removes one it no
+ * longer names, so the id is the declaration's key: stable across recomputes,
+ * never empty, and unique within a program because the compiler writes one per
+ * declaration.
+ */
+export interface ChartTableSpec extends ChartGrid {
+  readonly id: string;
+}
+
 /** One end of a drawing: a time on the shared axis, a price on the pane's scale. */
 export interface ChartAnchor {
   readonly time: number;

package/src/adapters/charts/tables.ts

@@ -27,13 +27,17 @@
  * placed into it, which is what `language.md` 6.7 asks for from the other
  * direction: a cell nothing was written into is blank, never a zero.
  *
- * **A chart pane holds one grid and the language declares as many as it likes.**
- * The descriptor has one `table` hook, and merging two grids into it would put
- * cells somewhere the script never asked for. So a program declaring a second
- * grid never reaches this file: `undrawable.ts` refuses it before any bar runs,
- * with OS6024, and this reads the one grid a program that runs can have.
- * `spec/chart-narrowings.json` records the refusal and
- * `scripts/check-chart-surface.mjs` proves it with a study that declares two.
+ * **The language declares as many grids as it likes, and a chart with the list
+ * of grids draws them all** (`capabilities.ts` says which chart has it). The
+ * list holds each grid under an id the chart keeps it by, and every declared
+ * grid is built for it here under its declaration's key. The single `table`
+ * hook stays beside the list with the first grid in it, because a chart
+ * without the list reads that one. Merging two grids into the single hook
+ * would put cells somewhere the script never asked for, so on a chart without
+ * the list a program declaring a second grid never reaches this file:
+ * `undrawable.ts` refuses it before any bar runs, with OS6024.
+ * `spec/chart-narrowings.json` records both halves and
+ * `scripts/check-chart-surface.mjs` proves both with a study that declares two.
  */
 import type { CompiledProgram, Grid as DeclaredGrid } from '../../core/emit/index.js';
 import type { Grid, GridCell } from '../../core/engine/index.js';
@@ -45,6 +49,7 @@ import type {
   ChartCellAlign,
   ChartGrid,
   ChartTablePosition,
+  ChartTableSpec,
 } from './surfaces.js';
 
 /** The language's four corners, in the chart's own words. */
@@ -58,22 +63,34 @@ const CORNERS: Readonly<Record<string, ChartTablePosition>> = {
 const ALIGNMENTS: readonly string[] = ['left', 'center', 'right'];
 
 /**
- * The grid a chart draws, from the declaration and the engine's buffer.
+ * Every grid a chart draws, from the declarations and the engine's buffers.
  *
- * The buffer is paired with the declaration by the key both of them carry
+ * Each buffer is paired with its declaration by the key both of them carry
  * rather than by position. The engine reads its grids in declaration order, so
  * the two agree today, and a pairing by position is one reordering away from
  * drawing one grid's cells into another grid's shape, which would be a wrong
  * table that looks like a right one.
+ *
+ * The key is the id as well. The compiler writes one per declaration and never
+ * an empty one, and it does not move between recomputes, which is what lets the
+ * chart keep a grid rather than build it again on every tick.
  */
-export function buildTable(
+export function buildTables(
   program: CompiledProgram,
   lookup: InputLookup,
   written: readonly Grid[],
-): ChartGrid | null {
-  const declared = program.outputs.tables[0];
-  if (declared === undefined) return null;
-  return oneTable(declared, lookup, written.find((one) => one.key === declared.key));
+): readonly ChartTableSpec[] {
+  return program.outputs.tables.map((declared) => ({
+    id: declared.key,
+    ...oneTable(declared, lookup, written.find((one) => one.key === declared.key)),
+  }));
+}
+
+/** The first grid alone, for the single hook a chart without the list reads. */
+export function firstGrid(tables: readonly ChartTableSpec[]): ChartGrid | null {
+  const first = tables[0];
+  if (first === undefined) return null;
+  return { rows: first.rows, ...(first.options === undefined ? {} : { options: first.options }) };
 }
 
 function oneTable(