openalgo-script 0.1.0-alpha.1 → 0.2.0

package/src/adapters/charts/settings.ts

@@ -0,0 +1,273 @@
+/**
+ * The declared inputs, in both directions.
+ *
+ * Out: one settings row per `input()` call, which is the whole of the generated
+ * settings dialog. The program already carries the label, the group, the help
+ * text, the bounds and the choices, because a settings dialog and a legend have
+ * to exist before the first bar runs, so nothing here decides anything. It
+ * translates a `kind` into the control a chart renders.
+ *
+ * Back in: what a dialog stored, turned into the values the engine validates.
+ * Two kinds need work and the rest pass through untouched. A colour arrives as a
+ * CSS string and has to become four numbers. A choice arrives as a string even
+ * when the script wrote numbers, because a select control has string values, so
+ * the stored string is matched against the declared options and the option's own
+ * value is what the engine is given.
+ *
+ * **A value the host stored and this module cannot convert is passed through
+ * rather than replaced.** The engine refuses it with OS6019, naming the key and
+ * the rule it broke. Substituting the default here would be a settings dialog
+ * that silently ignores what a user typed, which is the failure `2.6` is written
+ * to prevent, and it would hide it one layer further down than the engine does.
+ *
+ * **And a stored value the engine will refuse is not a value this adapter has.**
+ * The declared shape is built before anything runs, so a settings map holding a
+ * precision of 99 against an input declared `max = 8` put 99 into
+ * `plots[0].priceFormat`, which a host can show in a legend or on a price scale
+ * before the calculation that refuses it has been asked for. What a stored value
+ * is worth has one answer and it is the engine's own: `checkSetting` is the
+ * function the load refuses with, asked here before the load exists. A value it
+ * will not take reads as the **declared default** in the declared shape, and
+ * travels to the engine exactly as the host stored it, so the run still stops
+ * with OS6019 naming the key and the bound.
+ *
+ * Neither half of that is a fallback. The value is not repaired, because the
+ * same map still refuses; and the shape is not withheld, because the settings
+ * dialog a reader corrects the value in is built from the descriptor, and a
+ * study that refuses to describe itself is one whose bad setting cannot be
+ * reached. What a host is handed meanwhile is the shape the script declared,
+ * which is the shape the study has until a settings map the engine takes
+ * arrives.
+ */
+import type { CompiledInput, CompiledProgram, Constant } from '../../core/emit/index.js';
+import { checkSetting, constantValue } from '../../core/engine/index.js';
+import type { ColourValue, Value } from '../../core/engine/index.js';
+import { cssColour, isColourValue, parseColour } from './colours.js';
+import type { ChartInput, ChartSettings, ChartSource } from './contract.js';
+import type { InputLookup } from './fields.js';
+
+/** The eight series a `"source"` input may select, in the order 2.6 lists them. */
+const SOURCES: readonly string[] = [
+  'open',
+  'high',
+  'low',
+  'close',
+  'hl2',
+  'hlc3',
+  'ohlc4',
+  'volume',
+];
+
+/** One settings row per declared input, in source order. */
+export function inputRows(program: CompiledProgram): readonly ChartInput[] {
+  const rows: ChartInput[] = [];
+  for (const declared of program.inputs) rows.push(rowFor(declared));
+  return rows;
+}
+
+/**
+ * What the engine is handed as the host's settings.
+ *
+ * Only the declared keys travel. A chart's settings object also carries the
+ * generated per-plot appearance keys and the chart's timezone, and an engine
+ * given those would have nothing to do with them; leaving them out keeps the
+ * two vocabularies from having to agree on anything but the input keys.
+ */
+export function engineSettings(
+  program: CompiledProgram,
+  settings: ChartSettings,
+): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const declared of program.inputs) {
+    const supplied = storedValue(declared, settings);
+    if (supplied !== undefined) out[declared.key] = supplied;
+  }
+  return out;
+}
+
+/** The value each declared input currently holds, for a declaration field. */
+export function lookupFor(program: CompiledProgram, settings: ChartSettings): InputLookup {
+  return (key: string): Value => {
+    const declared = program.inputs.find((one) => one.key === key);
+    if (declared === undefined) return null;
+    return effectiveValue(declared, settings);
+  };
+}
+
+/**
+ * A comparable spelling of every declared input's value.
+ *
+ * The incremental path is only valid while the engine it holds was loaded from
+ * the same settings, and comparing the two spellings is cheaper and safer than
+ * trusting a chart to have told us that a settings change happened.
+ *
+ * **It spells what the engine is handed, not what the declared shape shows.**
+ * Those part company the moment a stored value is one the engine refuses: every
+ * refused value shows the same declared default, so a signature taken from the
+ * shape would read a change from a setting that runs to one that cannot as no
+ * change at all, keep the held engine and go on drawing the old numbers instead
+ * of reporting OS6019. The kind is spelled beside the value for the same
+ * reason: a stored `7` and a stored `"7"` are one quotation mark apart, and one
+ * of them is refused.
+ */
+export function signatureOf(program: CompiledProgram, settings: ChartSettings): string {
+  const parts: string[] = [];
+  for (const declared of program.inputs) {
+    parts.push(`${declared.key}=${spellStored(storedValue(declared, settings))}`);
+  }
+  return parts.join('\u0000');
+}
+
+/** The declared default, as the value model holds it. */
+export function defaultValue(declared: CompiledInput): Value {
+  return constantValue(declared.default);
+}
+
+function rowFor(declared: CompiledInput): ChartInput {
+  const held = defaultValue(declared);
+  const label = declared.label;
+  const key = declared.key;
+  const extra = {
+    ...(declared.group === '' ? {} : { group: declared.group }),
+    ...(declared.tooltip === null ? {} : { tooltip: declared.tooltip }),
+  };
+
+  // A choice is a choice whatever the type of its members. The compiled kind is
+  // `"select"` only where the values are strings, so a script that constrained a
+  // length to two numbers arrives as a number carrying options, and a spinner
+  // would offer every value between them: the engine validates a number against
+  // its bounds and not against its options, so nothing downstream would refuse
+  // the third value a user typed. The declared choices are the control.
+  const options = declared.options ?? [];
+  if (options.length > 0) {
+    return {
+      key,
+      type: 'select',
+      label,
+      default: spell(held),
+      options: options.map((one) => {
+        const text = spell(constantValue(one));
+        return { label: text, value: text };
+      }),
+      ...extra,
+    };
+  }
+
+  switch (declared.kind) {
+    case 'number':
+      return {
+        key,
+        type: 'number',
+        label,
+        default: typeof held === 'number' ? held : 0,
+        ...(declared.min === null ? {} : { min: declared.min }),
+        ...(declared.max === null ? {} : { max: declared.max }),
+        ...(declared.step === null ? {} : { step: declared.step }),
+        ...extra,
+      };
+    case 'bool':
+      return { key, type: 'boolean', label, default: held === true, ...extra };
+    case 'color':
+      return {
+        key,
+        type: 'color',
+        label,
+        default: isColourValue(held) ? cssColour(held) : 'rgba(0, 0, 0, 1)',
+        ...extra,
+      };
+    case 'source':
+      return {
+        key,
+        type: 'source',
+        label,
+        default: typeof held === 'string' && SOURCES.includes(held) ? (held as ChartSource) : 'close',
+        ...extra,
+      };
+    case 'interval':
+      return { key, type: 'interval', label, default: typeof held === 'string' ? held : '', ...extra };
+    case 'time':
+      return { key, type: 'time', label, default: typeof held === 'string' ? held : '', ...extra };
+    default:
+      return { key, type: 'text', label, default: typeof held === 'string' ? held : '', ...extra };
+  }
+}
+
+/** What the host stored for this input, converted, or nothing when it stored none. */
+function storedValue(declared: CompiledInput, settings: ChartSettings): unknown {
+  if (!Object.prototype.hasOwnProperty.call(settings, declared.key)) return undefined;
+  const supplied = settings[declared.key];
+  if (supplied === undefined) return undefined;
+
+  if (declared.kind === 'color' && typeof supplied === 'string') {
+    // A swatch has no alpha channel, so a stored colour that states none keeps
+    // the alpha the script declared. See `colours.ts`.
+    const held = defaultValue(declared);
+    const parsed = parseColour(supplied, isColourValue(held) ? held.a : 1);
+    return parsed ?? supplied;
+  }
+
+  if (declared.options !== null && typeof supplied === 'string') {
+    // The control's values are strings even where the declared choices are not,
+    // so a stored choice is matched on its own spelling and the engine is given
+    // the option the script wrote rather than the text of it.
+    const chosen = optionFor(declared.options, supplied);
+    return chosen === undefined ? supplied : chosen;
+  }
+
+  return supplied;
+}
+
+/**
+ * The effective value: the host's where the engine will run with it.
+ *
+ * The question is `checkSetting`'s, so there is no second list of types and
+ * bounds here to disagree with the first. This file decides only what to do
+ * with the answer, and the module's own paragraph says why a refused value
+ * reads as the declared default rather than as itself.
+ *
+ * One answer is narrowed and it is narrowed on purpose: a `"time"` input's
+ * stored string is read by the host's own conversion, which `run.ts` has and
+ * this has not, so a string is taken here and the load decides it.
+ */
+function effectiveValue(declared: CompiledInput, settings: ChartSettings): Value {
+  const stored = storedValue(declared, settings);
+  if (stored === undefined) return defaultValue(declared);
+  const checked = checkSetting(declared, stored);
+  return checked.ok ? checked.value : defaultValue(declared);
+}
+
+/** The declared option a stored string names, matched on its own spelling. */
+function optionFor(options: readonly Constant[], supplied: string): Value | undefined {
+  for (const option of options) {
+    const value = constantValue(option);
+    if (spell(value) === supplied) return value;
+  }
+  return undefined;
+}
+
+/**
+ * A stored value as the signature spells it, kind and all.
+ *
+ * Two stored values that spell one string are a settings change the incremental
+ * path does not notice, and a dialog stores numbers and text that look alike
+ * written out while the engine takes one and refuses the other. Every value of
+ * another kind spells the same word, which costs nothing: none of them can be
+ * behind a held engine, because the load that would have held one refused it.
+ */
+function spellStored(value: unknown): string {
+  if (value === undefined) return 'unset';
+  if (value === null) return 'none';
+  if (isColourValue(value as Value)) return `color ${cssColour(value as ColourValue)}`;
+  if (typeof value === 'number') return `number ${String(value)}`;
+  if (typeof value === 'boolean') return `bool ${String(value)}`;
+  if (typeof value === 'string') return `text ${value}`;
+  return 'of another kind';
+}
+
+/** A value as a settings control spells it. */
+function spell(value: Value): string {
+  if (value === null) return '';
+  if (isColourValue(value)) return cssColour(value);
+  if (typeof value === 'object') return '';
+  return String(value);
+}

package/src/adapters/charts/surfaces.ts

@@ -0,0 +1,238 @@
+/**
+ * The four surfaces that are not columns of numbers, as the chart declares them.
+ *
+ * A plot, a band and a level all reduce to one number per bar, so they ride the
+ * table a calculation returns. A marker, a grid, a drawing object and a watched
+ * condition do not: three of them carry text and the fourth carries geometry, and
+ * a chart reads each of them from its own hook on the descriptor rather than from
+ * the table. Their shapes are declared here, away from the calculation's, because
+ * they are read at a different moment and by a different part of the chart.
+ *
+ * **Every hook takes the run it is reading and not a handle to the study.** The
+ * argument is the bars, the table the calculation just returned and the settings
+ * it was run with, and there is no per-instance store among them. What travels
+ * through a hook is therefore what those three can carry, and what cannot is
+ * written down in `produced.ts`, which is the one place this adapter solves that
+ * problem.
+ *
+ * **Every member here is narrowed to what this adapter emits.** The chart draws
+ * more shapes, more marker positions and more grid options than the language has
+ * words for, and a value the language cannot express is better left out of this
+ * file than declared and never written. A narrower type stays assignable to the
+ * chart's wider one, which is what the one line in `contract.ts` checks.
+ */
+import type { ChartBar, ChartLineStyle, ChartSettings, ChartValues } from './contract.js';
+
+/** What every hook below is handed: the run whose output it is reading. */
+export interface ChartSurfaceContext {
+  readonly bars: readonly ChartBar[];
+  readonly values: ChartValues;
+  readonly settings: ChartSettings;
+}
+
+/**
+ * Where a marker sits against its bar.
+ *
+ * The language has three (`stdlib.md` 14.3) and the chart has six. `"above"` and
+ * `"below"` are the chart's own two, and `"price"` becomes the in-bar position:
+ * the language names no price to put the marker at, and a marker drawn at the
+ * close would be this adapter deciding which price `"price"` meant.
+ */
+export type ChartMarkerPosition = 'aboveBar' | 'belowBar' | 'inBar';
+
+/**
+ * The mark itself.
+ *
+ * Nine of the language's ten shapes are one of the chart's own under the same
+ * name. The tenth, `"label"`, is a plate of text with a tail that points at the
+ * anchor, so which of the chart's two plates it is follows from where the marker
+ * sits rather than from the word: a plate above the bar has its tail pointing
+ * down at it.
+ */
+export type ChartMarkerShape =
+  | 'arrowUp'
+  | 'arrowDown'
+  | 'triangleUp'
+  | 'triangleDown'
+  | 'circle'
+  | 'square'
+  | 'diamond'
+  | 'cross'
+  | 'flag'
+  | 'labelUp'
+  | 'labelDown'
+  | 'text';
+
+/** The four glyph sizes a chart draws a marker at. */
+export type ChartMarkerSize = 'tiny' | 'small' | 'medium' | 'big';
+
+/** One marker on one bar: a discrete event with a label, not a column. */
+export interface ChartMarker {
+  /** The bar's time, in the seconds a chart holds. */
+  readonly time: number;
+  readonly position: ChartMarkerPosition;
+  readonly shape: ChartMarkerShape;
+  readonly size: ChartMarkerSize;
+  readonly color: string;
+  readonly text?: string;
+}
+
+export type ChartCellAlign = 'left' | 'center' | 'right';
+
+/** One cell of a grid, as the last executed bar left it. */
+export interface ChartCell {
+  readonly text: string;
+  readonly textColor?: string;
+  readonly bgColor?: string;
+  readonly align?: ChartCellAlign;
+}
+
+/** Which corner of the pane a grid is pinned to. */
+export type ChartTablePosition =
+  | 'top-left'
+  | 'top-right'
+  | 'bottom-left'
+  | 'bottom-right';
+
+/** The grid options this adapter sets. A chart's own defaults fill the rest. */
+export interface ChartTableOptions {
+  readonly position: ChartTablePosition;
+  readonly borderWidth: number;
+  /** The backdrop behind the whole grid, which is the grid's own `bgColor`. */
+  readonly background?: string;
+}
+
+/** A grid of cells pinned to a corner, and the options it is drawn with. */
+export interface ChartGrid {
+  readonly rows: readonly (readonly ChartCell[])[];
+  readonly options?: ChartTableOptions;
+}
+
+/** One end of a drawing: a time on the shared axis, a price on the pane's scale. */
+export interface ChartAnchor {
+  readonly time: number;
+  readonly price: number;
+}
+
+/**
+ * One free-standing shape, anchored to time and price rather than to a bar.
+ *
+ * The four kinds are the language's four, `stdlib.md` 14.4, and the fields are
+ * the chart's own names for the same arguments. The whole list is replaced on
+ * every recompute, which is what makes a script that deletes an object have it
+ * disappear and a script that rolls a bar back not accumulate one per tick.
+ */
+export type ChartDrawing =
+  | {
+      readonly kind: 'line';
+      readonly from: ChartAnchor;
+      readonly to: ChartAnchor;
+      readonly color?: string;
+      readonly lineWidth?: number;
+      readonly lineStyle?: ChartLineStyle;
+      readonly extendLeft?: boolean;
+      readonly extendRight?: boolean;
+    }
+  | {
+      readonly kind: 'box';
+      readonly from: ChartAnchor;
+      readonly to: ChartAnchor;
+      readonly color?: string;
+      readonly fillColor?: string;
+      readonly opacity?: number;
+      readonly lineWidth?: number;
+      readonly text?: string;
+      readonly textColor?: string;
+      readonly tooltip?: string;
+    }
+  | {
+      readonly kind: 'label';
+      readonly at: ChartAnchor;
+      readonly text: string;
+      readonly color?: string;
+      readonly textColor?: string;
+      readonly align?: ChartCellAlign;
+      readonly tooltip?: string;
+    }
+  | {
+      readonly kind: 'polyline';
+      readonly points: readonly ChartAnchor[];
+      readonly color?: string;
+      readonly lineWidth?: number;
+      readonly closed?: boolean;
+      readonly fillColor?: string;
+      readonly opacity?: number;
+    };
+
+/** What an alert's condition is handed, for the bar it is judging. */
+export interface ChartAlertContext extends ChartSurfaceContext {
+  readonly index: number;
+}
+
+/**
+ * One watched condition, declared before bar 0 and evaluated by the chart.
+ *
+ * The chart judges bars that are new since it last looked, which is the rule
+ * `stdlib.md` 16.2 states from the other side: a study added to a chart holding
+ * two years of bars announces none of them.
+ */
+export interface ChartAlertSpec {
+  readonly id: string;
+  readonly title: string;
+  /**
+   * The notification's text, computed for the bar that fired.
+   *
+   * The chart takes either a fixed string or a function of the same context
+   * `when` was judged on, and it calls the function only for a bar `when`
+   * accepted. This adapter writes only the function: a declared alert's message
+   * is an expression evaluated on the bar, so a fixed string could only ever be
+   * the title again, which is what this used to hand over.
+   */
+  message?(ctx: ChartAlertContext): string;
+  when(ctx: ChartAlertContext): boolean;
+}
+
+/**
+ * Bars of another instrument or interval, as the host is asked for them.
+ *
+ * There is no cancellation token on it, and none is needed: a chart bounds every
+ * request it forwards by the study instance's own lifetime, so a study removed
+ * while another instrument is loading is not answered after it is gone. A second
+ * token carried from here would be the same fact stated twice, and the weaker of
+ * the two.
+ */
+export interface ChartBarsRequest {
+  readonly symbol: string;
+  readonly exchange?: string;
+  readonly interval: string;
+  /** UTC seconds, both ends. */
+  readonly from: number;
+  readonly to: number;
+}
+
+/** What a study says about the data it is waiting for. */
+export type ChartDataStatus =
+  | { readonly state: 'loading' | 'ready' | 'empty' | 'unsupported' }
+  | { readonly state: 'error'; readonly error: unknown };
+
+/** Why the host says the bars or the identity behind a study have moved. */
+export type ChartDataChange = 'context' | 'range';
+
+/**
+ * The lifecycle of one study instance, for the data that is not on its bars.
+ *
+ * It is the only place the chart offers a transport, and a read of another
+ * instrument is the only thing in this language that needs one. Everything else
+ * a study produces is computed from bars the chart already holds.
+ */
+export interface ChartAttachContext {
+  /** Scratch this instance owns: the same object the calculation receives. */
+  readonly store: Record<string, unknown>;
+  /** Ask the host for another instrument's bars. Absent when it serves none. */
+  requestBars?(request: ChartBarsRequest): Promise<readonly ChartBar[]>;
+  /** Run the calculation again and repaint, once an answer has arrived. */
+  requestRecompute(): void;
+  setDataStatus?(status: ChartDataStatus): void;
+  setDataRetry?(retry: (() => void) | null): void;
+  subscribeDataChanges?(listener: (change: ChartDataChange) => void): () => void;
+}

package/src/adapters/charts/tables.ts

@@ -0,0 +1,155 @@
+/**
+ * Declared grids into the chart's summary grid.
+ *
+ * **A table is written, not plotted.** It is the one output that is not a value
+ * per bar: its cells are written by library calls against a handle, into a
+ * buffer the engine empties at the start of every execution of a bar
+ * (`compiled-program.md` 2.8 and 5.1). What survives is what the last executed
+ * bar wrote, which is what a grid pinned to a corner of a pane shows.
+ *
+ * **So it is read once, after the run, and never per bar.** The obvious way to
+ * get this wrong is to collect a grid for every bar of a long history in order
+ * to display the last one, which costs the length of the history and throws all
+ * of it away. The engine holds one buffer per grid rather than one per bar, and
+ * this reads it exactly once per calculation, so a hundred thousand bars cost
+ * the same as ten.
+ *
+ * A script pays the other half of that bill for itself: `cell()` on every bar of
+ * a long history does the work of writing a grid that only the last bar's copy
+ * is kept from, and the documentation says to guard it with `bar.isLast`. That
+ * is a script's decision and not one this can make for it, because the buffer is
+ * cleared per bar and an engine cannot know which execution is the last one
+ * until it is.
+ *
+ * **The engine's cells are sparse and the chart's grid is dense.** A script
+ * writes the cells it has something to say about; the chart draws rows of cells.
+ * So the declared size is filled with blank cells and the written ones are
+ * 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, so the first declared grid is the one
+ * drawn and any after it are not. That is a gap in the chart's own contract
+ * rather than a choice worth making here: there is no second hook to write to,
+ * and merging two grids into one would put cells somewhere the script never
+ * asked for.
+ *
+ * **What ought to happen is a refusal, and it cannot be written yet.** A study
+ * whose second grid never appears is a study with no explanation, so the second
+ * `table()` should be refused where it is written, naming the limit. Every
+ * diagnostic in this project carries a catalogue code and the catalogue has
+ * none for "the chart cannot draw something this study declares"; inventing one
+ * here is the one thing that is not allowed, so the gap is reported instead, in
+ * `issues/0011-a-second-declared-grid-is-dropped-with-nothing-said.md`, with the
+ * sentence it should carry.
+ *
+ * Until it lands, the drop is at least no longer silent inside this repository:
+ * it is recorded in `spec/chart-narrowings.json` with its reason, and
+ * `scripts/check-chart-surface.mjs` fails the build if this adapter ever drops
+ * anything else a compiled program declares without recording it there.
+ */
+import type { CompiledProgram, Grid as DeclaredGrid } from '../../core/emit/index.js';
+import type { Grid, GridCell } from '../../core/engine/index.js';
+import { cssColour, cssOf } from './colours.js';
+import { colourField, numberField, stringField } from './fields.js';
+import type { InputLookup } from './fields.js';
+import type {
+  ChartCell,
+  ChartCellAlign,
+  ChartGrid,
+  ChartTablePosition,
+} from './surfaces.js';
+
+/** The language's four corners, in the chart's own words. */
+const CORNERS: Readonly<Record<string, ChartTablePosition>> = {
+  topLeft: 'top-left',
+  topRight: 'top-right',
+  bottomLeft: 'bottom-left',
+  bottomRight: 'bottom-right',
+};
+
+const ALIGNMENTS: readonly string[] = ['left', 'center', 'right'];
+
+/**
+ * The grid a chart draws, from the declaration and the engine's buffer.
+ *
+ * The buffer is paired with the 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.
+ */
+export function buildTable(
+  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));
+}
+
+function oneTable(
+  declared: DeclaredGrid,
+  lookup: InputLookup,
+  written: Grid | undefined,
+): ChartGrid {
+  const position = stringField(declared.position, lookup, 'topRight');
+  const textColour = colourField(declared.options.textColor, lookup);
+  const bgColour = colourField(declared.options.bgColor, lookup);
+  const rows = whole(numberField(declared.rows, lookup, 0));
+  const cols = whole(numberField(declared.cols, lookup, 0));
+  const fallback = textColour === undefined ? undefined : cssColour(textColour);
+
+  const grid: ChartCell[][] = [];
+  for (let row = 0; row < rows; row += 1) {
+    grid.push(new Array<ChartCell>(cols).fill({ text: '' }));
+  }
+  for (const cell of written?.cells ?? []) {
+    const built = oneCell(cell, fallback);
+    const line = grid[cell.row];
+    if (built === undefined || line === undefined || cell.col >= cols) continue;
+    line[cell.col] = built;
+  }
+
+  return {
+    rows: grid,
+    options: {
+      position: CORNERS[position] ?? 'top-right',
+      borderWidth: numberField(declared.options.borderWidth, lookup, 0),
+      ...(bgColour === undefined ? {} : { background: cssColour(bgColour) }),
+    },
+  };
+}
+
+/**
+ * One written cell, or none.
+ *
+ * A cell whose text is absent is dropped rather than drawn, which leaves the
+ * blank cell that was already in its place: absence reaching a drawing surface
+ * is a gap, and a blank cell is what a grid draws where nothing was written
+ * (`language.md` 6.7).
+ *
+ * The grid's own text colour is written into each cell that named none, because
+ * the chart carries a text colour per cell and the language declares one for the
+ * whole grid as well.
+ */
+function oneCell(cell: GridCell, fallback: string | undefined): ChartCell | undefined {
+  if (typeof cell.text !== 'string') return undefined;
+  const align = typeof cell.align === 'string' && ALIGNMENTS.includes(cell.align)
+    ? (cell.align as ChartCellAlign)
+    : 'left';
+  const textColour = cssOf(cell.textColor) ?? fallback;
+  const bgColour = cssOf(cell.bgColor);
+  return {
+    text: cell.text,
+    ...(textColour === undefined ? {} : { textColor: textColour }),
+    ...(bgColour === undefined ? {} : { bgColor: bgColour }),
+    align,
+  };
+}
+
+/** A declared size, as a count of rows or columns a grid can be built with. */
+function whole(size: number): number {
+  return size > 0 ? Math.floor(size) : 0;
+}