quario 0.4.0 → 0.6.0

package/lib/plan.js

@@ -43,9 +43,12 @@ import {
   relocate as relocateTemplate,
   template,
 } from "sjabloon";
+import { pinGuard } from "./band-height.js";
 import { LOCATION, fault, isDiagnostic, locate } from "./locate.js";
 import { ANCHORS, BLOCKED, NAME, RESERVED, record } from "./names.js";
-import { AGG, REDUCERS, RUN, aggregateValue, withRow } from "./scope.js";
+import { MATH } from "./math.js";
+import { REDUCERS, reducerFor } from "./reducers.js";
+import { aggregateValue, withRow } from "./scope.js";
 import { opt, sniff } from "./stream.js";
 import {
   checkBorderSides,
@@ -54,8 +57,18 @@ import {
   checkReportStyle,
   checkRowStyle,
   checkSlotImageStyle,
+  checkItemStyle,
   checkSlotStyle,
   checkStyle,
+  boxReaching,
+  coveredNames,
+  fanBox,
+  guarded,
+  isBoxName,
+  isExpr,
+  positivePts,
+  resolveFormat,
+  SKIP,
 } from "./style.js";
 
 // Tolerance on the column-width sum. Widths are literal numbers an author may
@@ -67,13 +80,46 @@ let WIDTH_EPS = 1e-9;
 // plan rather than riding the state a plan accumulates.
 /** @type {any} */
 let NIL = () => null;
+// The two halves a table row's `style` compiles to, and the pair a row that
+// declares none wears.
+/** @typedef {{ box: (scope: Scope) => any, names: string[], rest: (scope: Scope) => any }} RowStyles */
+/** @typedef {{ styles: RowStyles, visible: any, cells: any[], fan: (string[] | null)[] }} TotalRow */
+/** @typedef {{ visible: any, rows: readonly TotalRow[] }} TotalBlock */
+// One declaration compiled: its name, what it resolves to, and whether that
+// defers to render. The third is what lets two blocks compose without the
+// documents they came from -- see `underRow`.
+/** @typedef {[string, Eval, boolean]} StyleEntry */
+/** @typedef {{ box: StyleEntry[], rest: StyleEntry[] }} RowEntries */
+/** @type {RowEntries} */
+let NO_ROW_ENTRIES = { box: [], rest: [] };
+/** @type {RowStyles} */
+let NO_ROW_STYLE = { box: NIL, names: [], rest: NIL };
+// A cell that declares no readable style block: nothing to resolve, and no
+// box name to keep any of its row's box off it.
+let NO_CELL_LOOK = { styles: NIL, box: /** @type {string[]} */ ([]) };
+// An absent `total` is the block with no rows. `rows: []` is a definition
+// error, so an empty one can only have come from absence and nothing has to
+// tell the two apart downstream.
+/** @type {TotalBlock} */
+let NO_TOTALS = Object.freeze({ visible: null, rows: Object.freeze([]) });
 /** @type {any} */
 let EMPTY = () => [];
 // What `$.params` reads when a report declares none.
 let NONE = Object.freeze({});
 
-/** @type {(value: any) => boolean} */
-let isExpr = (value) => typeof value === "string" && value[0] === "=";
+// How many table columns one cell covers. A literal, for the same reason a
+// column `width` is: the column geometry is allocated before any row is laid
+// out, so it cannot depend on one. Absent is 1, and an unreadable span reads
+// as 1 so the coverage walk above it reports where the author actually went
+// wrong instead of cascading. `spanned` is the emit side: a span of 1 is the
+// absence of one, and never reaches the stream.
+/** @type {(span: any) => number} */
+let spanValue = (span) => (Number.isInteger(span) && span >= 1 ? span : 1);
+/** @type {(span: any) => boolean} */
+let validSpan = (span) => span == null || spanValue(span) === span;
+/** @type {(span: number) => number} */
+let spanned = (span) => (span > 1 ? span : 0);
+
 /** @type {(from: Iterable<string>, into: Set<string>) => void} */
 let collect = (from, into) => {
   for (let name of from) into.add(name);
@@ -204,6 +250,7 @@ let jsonCopy = (value, path, bad, seen) => {
 /** @typedef {import("./scope.js").Scope} Scope */
 /** @typedef {import("./scope.js").Eval} Eval */
 /** @typedef {import("./scope.js").Fold} Fold */
+/** @typedef {import("./reducers.js").Role} Role */
 /** @typedef {import("./scope.js").RunnerSet} RunnerSet */
 /** @typedef {(rows: any[], scope: Scope, runners: RunnerSet) => Generator<any>} Band */
 /** @typedef {ReturnType<typeof planState>} State */
@@ -240,7 +287,10 @@ let bindHandles = (schema, bound) => {
  */
 let planState = (schema, funcs) => {
   /** @type {Record<string, (...args: any[]) => any>} */
-  let FNS = /** @type {any} */ ({ ...REDUCERS, ...funcs });
+  // Built-in functions first, the host's registry last: a `funcs` entry of the
+  // same name shadows a built-in, which is the rule SCHEMA.md states for the
+  // reducers and which the scalar built-ins join rather than complicate.
+  let FNS = /** @type {any} */ ({ ...REDUCERS, ...MATH, ...funcs });
   /** @type {Set<string>} */
   let names = new Set();
   /** @type {Set<string>} */
@@ -333,6 +383,10 @@ let planState = (schema, funcs) => {
     add,
     bad,
     attempt,
+    // The band-height rule, carried by the descent rather than walked
+    // separately: `traverse` arms it from the report header and offers it each
+    // band below (./band-height.js).
+    pin: pinGuard(bad),
     diagnostic: () => firstDiag,
   };
 };
@@ -382,10 +436,14 @@ let splitFold = (spec) => {
   if (colon < 0) return { fn: spec, src: "", colon };
   return { fn: spec.slice(0, colon), src: spec.slice(colon + 1), colon };
 };
-/** @type {(colon: number, path: string) => void} */
-let checkCount = (colon, path) => {
+// The two spellings a reducer's declared form takes, one per `expr` flag on its
+// registry entry — `checkBareFold` for a false one, `checkExprFold` for a true.
+// Neither names a reducer: `count` is only the entry that happens to carry
+// `expr: false` today, and another would be refused the same way.
+/** @type {(colon: number, fn: string, path: string) => void} */
+let checkBareFold = (colon, fn, path) => {
   // oxlint-disable-next-line no-unused-expressions
-  colon < 0 || fault(path, "count does not take an expression");
+  colon < 0 || fault(path, fn + " does not take an expression");
 };
 /** @type {(src: string, fn: string, path: string) => void} */
 let checkExprFold = (src, fn, path) => {
@@ -427,15 +485,17 @@ let primitives = ({ FNS, BND, names, functions, anchorsOf }) => {
     return runCell(tokens, path, source);
   };
 
-  // Parse "reducer:=expr" into a reducer name and a compiled per-row expression
-  // (null for `count`, which takes no expression).
-  /** @type {(spec: string, path: string, allowed: Set<string>) => Fold} */
-  let parseFold = (spec, path, allowed) => {
+  // Parse "reducer:=expr" into a reducer name and a compiled per-row expression,
+  // null where the entry's `expr` flag says the form carries none.
+  /** @type {(spec: string, path: string, role: Role) => Fold} */
+  let parseFold = (spec, path, role) => {
     let { fn, src, colon } = splitFold(spec);
-    // oxlint-disable-next-line no-unused-expressions
-    allowed.has(fn) || fault(path, 'unknown reducer "' + fn + '"');
-    if (fn === "count") checkCount(colon, path);
-    else checkExprFold(src, fn, path);
+    // The role decides the vocabulary: a reducer with no whole-array fold is a
+    // running value only, so `prev` is an unknown reducer under `aggregates`.
+    let reducer = reducerFor(role, fn);
+    if (!reducer) fault(path, 'unknown reducer "' + fn + '"');
+    if (reducer.expr) checkExprFold(src, fn, path);
+    else checkBareFold(colon, fn, path);
     return { fn, per: src ? prop(src, path) : null };
   };
 
@@ -451,7 +511,7 @@ let primitives = ({ FNS, BND, names, functions, anchorsOf }) => {
  * @param {State} state
  * @param {Primitives} primitives
  */
-let readers = ({ bad, attempt }, { prop, cell, parseFold }) => {
+let readers = ({ bad, attempt }, { prop, cell, parseFold }, /** @type {any} */ options) => {
   /** @type {(value: any, path: string) => boolean} */
   let obj = (value, path) => {
     if (record(value)) return true;
@@ -544,51 +604,152 @@ let readers = ({ bad, attempt }, { prop, cell, parseFold }) => {
   // CSS). An all-literal block folds to one frozen object at compile time.
   /**
    * @type {(block: any, path: string, check: (name: string, value: any) => string | null)
-   *   => [string, Eval][]}
+   *   => StyleEntry[]}
    */
   let readStyles = (block, path, check) => {
-    /** @type {[string, Eval][]} */
+    /** @type {StyleEntry[]} */
     let entries = [];
     for (let [name, value] of Object.entries(block)) {
       let stylePath = path + "." + name;
       let problem = check(name, value);
       if (problem) bad(stylePath, problem);
-      else entries.push([name, attempt(() => prop(value, stylePath), NIL)]);
+      else {
+        // A literal has already passed `check` above and can never fail at
+        // render, so only an `=` result is wrapped in the rule its name
+        // answers to. `style.js` owns which rule that is (docs/adr/0055).
+        let resolve = attempt(() => prop(value, stylePath), NIL);
+        let expr = isExpr(value);
+        entries.push([name, expr ? guarded(name, resolve) : resolve, expr]);
+      }
     }
     return entries;
   };
-  /** @type {(entries: [string, Eval][]) => (scope: Scope) => Scope} */
+  // The names are written in declaration order, which the stream promises, so
+  // a guarded name that answers is written where it was declared rather than
+  // after the ones that never needed guarding.
+  //
+  // `format` resolves after the loop rather than inside it, and the order is
+  // what makes that necessary: a `currency` kind takes its digit count from
+  // the code the cell wears, so the code has to have been written -- or
+  // voided by `guarded` -- before the kind can be resolved over it. Doing it
+  // per entry would make one declaration depend on where another sits in the
+  // block. The instance's options come with it, for the cell that declares no
+  // code of its own and takes the instance's (docs/adr/0056).
+  /** @type {(entries: StyleEntry[]) => (scope: Scope) => Scope} */
   let styleFn = (entries) => (scope) => {
     /** @type {Scope} */
     let style = {};
-    for (let [name, value] of entries) style[name] = value(scope);
-    return style;
+    for (let [name, value] of entries) {
+      let resolved = value(scope);
+      if (resolved !== SKIP) style[name] = resolved;
+    }
+    return resolveFormat(style, options);
   };
-  /** @type {(block: any) => boolean} */
-  let isComputed = (block) => Object.values(block).some(isExpr);
   /**
    * @type {(block: any, path: string, check: (name: string, value: any) => string | null)
    *   => (scope: Scope) => any}
    */
-  let compileStyles = (block, path, check) => {
-    let entries = readStyles(block, path, check);
-    for (let [name, msg] of checkBorderSides(block, check)) bad(path + "." + name, msg);
+  // A compiled block, constant-folded when nothing in it defers to render, so
+  // a literal style is resolved once and every node that wears it is handed
+  // the same frozen object.
+  /** @type {(entries: StyleEntry[]) => (scope: Scope) => any} */
+  let folded = (entries) => {
     if (!entries.length) return NIL;
     let resolve = styleFn(entries);
-    if (isComputed(block)) return resolve;
+    if (entries.some((entry) => entry[2])) return resolve;
     let constant = Object.freeze(resolve({}));
     return () => constant;
   };
   /**
-   * @type {(def: any, path: string, check?: (name: string, value: any) => string | null)
+   * @type {(block: any, path: string, check: (name: string, value: any) => string | null)
+   *   => StyleEntry[]}
+   */
+  let styleEntries = (block, path, check) => {
+    let entries = readStyles(block, path, check);
+    for (let [name, msg] of checkBorderSides(block, check)) bad(path + "." + name, msg);
+    return entries;
+  };
+  /**
+   * @type {(block: any, path: string, check: (name: string, value: any) => string | null)
    *   => (scope: Scope) => any}
    */
-  let stylesOf = (def, path, check = checkStyle) => {
+  // A table row's block is split where it is compiled rather than at every
+  // row: its box half resolves onto the row's cells and the rest stays on the
+  // row (SCHEMA.md, "Style declarations"). Both halves fold like any other
+  // block, so a literal row style is partitioned once per table.
+  /** @type {(def: any, path: string) => RowEntries} */
+  let rowEntriesOf = (def, path) => {
+    let block = def.style;
+    let stylePath = pathTo(path, "style");
+    if (block == null || !obj(block, stylePath)) return NO_ROW_ENTRIES;
+    let entries = styleEntries(block, stylePath, checkRowStyle);
+    return {
+      box: entries.filter(([name]) => isBoxName(name)),
+      rest: entries.filter(([name]) => !isBoxName(name)),
+    };
+  };
+  /**
+   * One row block under another: the totals block's under a total row's. The
+   * row's names win, and its box takes any border side it speaks for whole --
+   * the same rule a cell applies over a row, settled here on the names rather
+   * than at render on the values, so the block leaves no third level behind
+   * (docs/adr/0049). A row that composes to all-literal folds to one frozen
+   * object like any other block.
+   *
+   * @type {(under: RowEntries, over: RowEntries) => RowEntries}
+   */
+  let underRow = (under, over) => {
+    if (!under.box.length && !under.rest.length) return over;
+    let box = coveredNames(over.box.map(([name]) => name));
+    let rest = new Set(over.rest.map(([name]) => name));
+    return {
+      box: [...under.box.filter(([name]) => !box.has(name)), ...over.box],
+      rest: [...under.rest.filter(([name]) => !rest.has(name)), ...over.rest],
+    };
+  };
+  /** @type {(entries: RowEntries) => RowStyles} */
+  let foldRow = ({ box, rest }) => ({
+    box: folded(box),
+    names: box.map(([name]) => name),
+    rest: folded(rest),
+  });
+  // The entries a node's `style` compiles to, or none when it declares no
+  // readable block. Every caller folds them; a table cell keeps their box
+  // names first.
+  /**
+   * @type {(def: any, path: string, check: (name: string, value: any) => string | null)
+   *   => StyleEntry[] | null}
+   */
+  let entriesOf = (def, path, check) => {
     let block = def.style;
     let stylePath = pathTo(path, "style");
-    if (block == null || !obj(block, stylePath)) return NIL;
-    return compileStyles(block, stylePath, check);
+    if (block == null || !obj(block, stylePath)) return null;
+    return styleEntries(block, stylePath, check);
   };
+  /**
+   * @type {(def: any, path: string, check?: (name: string, value: any) => string | null)
+   *   => (scope: Scope) => any}
+   */
+  let stylesOf = (def, path, check = checkStyle) => {
+    let entries = entriesOf(def, path, check);
+    return entries ? folded(entries) : NIL;
+  };
+  // A cell's compiled style with the box names it declared kept beside it.
+  // Those names are what settles which of its row's box reaches it -- the
+  // question `layer` used to ask of the resolved object at render, asked once
+  // here instead (docs/adr/0056).
+  /** @type {(def: any, path: string) => { styles: (scope: Scope) => any, box: string[] }} */
+  let cellLook = (def, path) => {
+    let entries = entriesOf(def, path, checkCellStyle);
+    if (!entries) return NO_CELL_LOOK;
+    return {
+      styles: folded(entries),
+      box: entries.filter(([name]) => isBoxName(name)).map(([name]) => name),
+    };
+  };
+  /** The same, for the blocks that sit on a table row. */
+  /** @type {(def: any, path: string) => RowStyles} */
+  let rowStylesOf = (def, path) => foldRow(rowEntriesOf(def, path));
   // A cell value: one sjabloon template. Emphasis is the cell's own `style`;
   // markup in literal text is meaningful only to the HTML target.
   /** @type {(value: any, path: string) => (scope: Scope, opts?: any) => any} */
@@ -603,43 +764,43 @@ let readers = ({ bad, attempt }, { prop, cell, parseFold }) => {
     if (seen.has(name)) bad(foldPath, 'duplicate run name "' + name + '"');
     else seen.add(name);
   };
-  /** @type {(spec: any, foldPath: string, allowed: Set<string>) => Fold | null} */
-  let readFold = (spec, foldPath, allowed) => {
+  /** @type {(spec: any, foldPath: string, role: Role) => Fold | null} */
+  let readFold = (spec, foldPath, role) => {
     if (typeof spec !== "string") {
       bad(foldPath, "expected a reducer specification");
       return null;
     }
-    return attempt(() => parseFold(spec, foldPath, allowed), null);
+    return attempt(() => parseFold(spec, foldPath, role), null);
   };
-  /** @type {(name: string, spec: any, path: string, allowed: Set<string>, reserved: Set<string> | null, seen?: Set<string>) => [string, Fold] | null} */
-  let oneFold = (name, spec, path, allowed, reserved, seen) => {
+  /** @type {(name: string, spec: any, path: string, role: Role, reserved: Set<string> | null, seen?: Set<string>) => [string, Fold] | null} */
+  let oneFold = (name, spec, path, role, reserved, seen) => {
     let foldPath = path + "." + name;
     named(name, foldPath, reserved);
     noteRun(seen, name, foldPath);
-    let fold = readFold(spec, foldPath, allowed);
+    let fold = readFold(spec, foldPath, role);
     return fold && [name, fold];
   };
   /**
-   * @type {(value: any, path: string, allowed: Set<string>,
+   * @type {(value: any, path: string, role: Role,
    *   reserved: Set<string> | null, seen?: Set<string>) => [string, Fold][]}
    */
-  let readFolds = (value, path, allowed, reserved, seen) => {
+  let readFolds = (value, path, role, reserved, seen) => {
     /** @type {[string, Fold][]} */
     let out = [];
     for (let [name, spec] of Object.entries(value)) {
-      let fold = oneFold(name, spec, path, allowed, reserved, seen);
+      let fold = oneFold(name, spec, path, role, reserved, seen);
       if (fold) out.push(fold);
     }
     return out;
   };
   // Declared aggregates and running values, both spelled "reducer:=expr".
   /**
-   * @type {(value: any, path: string, allowed: Set<string>,
+   * @type {(value: any, path: string, role: Role,
    *   reserved: Set<string> | null, seen?: Set<string>) => [string, Fold][]}
    */
-  let foldsOf = (value, path, allowed, reserved, seen) => {
+  let foldsOf = (value, path, role, reserved, seen) => {
     if (value == null || !obj(value, path)) return [];
-    return readFolds(value, path, allowed, reserved, seen);
+    return readFolds(value, path, role, reserved, seen);
   };
   /** @type {(dir: any, path: string) => void} */
   let checkDir = (dir, path) => {
@@ -703,6 +864,11 @@ let readers = ({ bad, attempt }, { prop, cell, parseFold }) => {
     columnsOf,
     takeOf,
     stylesOf,
+    cellLook,
+    rowStylesOf,
+    rowEntriesOf,
+    underRow,
+    foldRow,
     cellValue,
     foldsOf,
     sortOf,
@@ -718,7 +884,7 @@ let readers = ({ bad, attempt }, { prop, cell, parseFold }) => {
  * @param {State} state
  * @param {Readers} readers
  */
-let nodes = ({ bad }, { arr, obj, keys, expression, cellValue, visibleOf, stylesOf }) => {
+let nodes = ({ bad }, { arr, obj, keys, expression, cellValue, visibleOf, stylesOf, cellLook }) => {
   // `tokens` plus its truthy `style`. A hidden cell keeps its slot with no
   // tokens so a column keeps its alignment; items pass `visible` null and drop
   // themselves instead, having no slot to keep. The anchor story lives on
@@ -731,24 +897,65 @@ let nodes = ({ bad }, { arr, obj, keys, expression, cellValue, visibleOf, styles
     opt({ tokens: hidden(visible, scope) ? [] : tpl(scope) }, { style: styles(scope) });
 
   // A table cell: the shape of a total cell and of an object column header.
-  /** @type {(def: any, path: string, valuePath?: string) => (scope: Scope) => any} */
+  /**
+   * @type {(def: any, path: string, valuePath?: string) =>
+   *   { cell: (scope: Scope) => any, box: string[] }}
+   */
   let cellOf = (def, path, valuePath = path + ".value") => {
     let tpl = cellValue(def.value, valuePath);
     let visible = visibleOf(def, path);
-    return cellShape(tpl, visible, stylesOf(def, path, checkCellStyle));
+    let look = cellLook(def, path);
+    return { cell: cellShape(tpl, visible, look.styles), box: look.box };
+  };
+
+  /** @type {(def: any, path: string) => number} */
+  let spanOf = (def, path) => {
+    if (validSpan(def.span)) return spanValue(def.span);
+    bad(path + ".span", "expected a positive integer (span >= 1)");
+    return 1;
   };
 
   // A cell without a row, so `@` stays unbound. A bare string is shorthand for
   // `{ value }` and keeps its authored path, so problems locate where written.
-  /** @type {(def: any, path: string) => (scope: Scope) => any} */
+  // A span needs the object form -- a bare string has nowhere to carry one.
+  // Absent is a problem here: a column that legitimately declares no header is
+  // one a neighbour's span covers, and `headerSlot` answers that before this
+  // is reached.
+  /**
+   * @type {(def: any, path: string) =>
+   *   { cell: (scope: Scope) => any, span: number, box: string[] }}
+   */
   let headerOf = (def, path) => {
-    if (typeof def === "string") return cellShape(cellValue(def, path), null, NIL);
+    if (typeof def === "string")
+      return { cell: cellShape(cellValue(def, path), null, NIL), span: 1, box: NO_CELL_LOOK.box };
     if (!record(def)) {
       bad(path, "expected a template string or object");
-      return cellShape(EMPTY, null, NIL);
+      return { cell: cellShape(EMPTY, null, NIL), span: 1, box: NO_CELL_LOOK.box };
     }
-    keys(def, ["value", "style"], path);
-    return cellOf(def, path);
+    keys(def, ["value", "style", "span"], path);
+    return { ...cellOf(def, path), span: spanOf(def, path) };
+  };
+
+  // A column a neighbour's span covers declares no header of its own. One that
+  // declares one anyway is the overlap half of the coverage rule.
+  /** @type {(def: any, path: string) => null} */
+  let covered = (def, path) => {
+    if (def != null) bad(path, "covered by an earlier header's span");
+    return null;
+  };
+  // The per-column half of the coverage rule. `headerCover` decides which slot
+  // a column is in; this reports it, in the column's own turn, so header
+  // problems still come out in the documented key order.
+  /**
+   * @type {(def: any, path: string, slot: string) =>
+   *   { cell: (scope: Scope) => any, span: number, box: string[] } | null}
+   */
+  let headerSlot = (def, path, slot) => {
+    if (slot === "unreached") return null;
+    if (slot === "covered") return covered(def, path);
+    let header = headerOf(def, path);
+    if (slot === "over") bad(path + ".span", "reaches past the last column");
+    return header;
   };
 
   /** @type {(width: any) => boolean} */
@@ -759,25 +966,34 @@ let nodes = ({ bad }, { arr, obj, keys, expression, cellValue, visibleOf, styles
     bad(path + ".width", "expected a percentage number (0 < width <= 100)");
     return NaN;
   };
-  /** @type {(def: any, path: string) => any} */
-  let columnOf = (def, path) => {
+  /** @type {(def: any, path: string, slot: string) => any} */
+  let columnOf = (def, path, slot) => {
     if (!obj(def, path)) return null;
     keys(def, ["header", "value", "visible", "style", "width"], path);
-    let header = headerOf(def.header, path + ".header");
+    let header = headerSlot(def.header, path + ".header", slot);
     let tpl = cellValue(def.value, path + ".value");
     let visible = visibleOf(def, path);
-    let styles = stylesOf(def, path, checkCellStyle);
+    let look = cellLook(def, path);
     // A width is a percentage of the table width, resolved by every target.
     // The range verdict is owned here: an unreadable width comes back as NaN,
     // so the total check below reads the verdict instead of re-deciding it.
-    return { header, cell: cellShape(tpl, visible, styles), width: widthOf(def.width, path), path };
+    return {
+      header,
+      cell: cellShape(tpl, visible, look.styles),
+      box: look.box,
+      width: widthOf(def.width, path),
+      path,
+    };
   };
 
-  /** @type {(def: any, path: string) => ((scope: Scope) => any) | null} */
+  /**
+   * @type {(def: any, path: string) =>
+   *   { cell: (scope: Scope) => any, span: number, box: string[] } | null}
+   */
   let totalOf = (def, path) => {
     if (!obj(def, path)) return null;
-    keys(def, ["value", "visible", "style"], path);
-    return cellOf(def, path);
+    keys(def, ["value", "visible", "style", "span"], path);
+    return { ...cellOf(def, path), span: spanOf(def, path) };
   };
 
   // A text item: a cell with no slot to keep, so a hidden one drops itself
@@ -793,7 +1009,7 @@ let nodes = ({ bad }, { arr, obj, keys, expression, cellValue, visibleOf, styles
     let shape = cellShape(
       tpl,
       inSlot ? visible : null,
-      stylesOf(def, path, inSlot ? checkSlotStyle : checkStyle),
+      stylesOf(def, path, inSlot ? checkSlotStyle : checkItemStyle),
     );
     // The cell shape first, then the item's own fields, so a cell reads
     // the same wherever it appears in the stream.
@@ -843,7 +1059,14 @@ let nodes = ({ bad }, { arr, obj, keys, expression, cellValue, visibleOf, styles
         TypeError("expected a Uint8Array of PNG or JPEG bytes"),
       );
     return opt(
-      { type: "image", role: fields.role, bytes, format, fit: fields.fit, path: fields.path },
+      {
+        type: "image",
+        role: fields.role,
+        bytes,
+        format,
+        fit: fields.fit,
+        path: fields.path,
+      },
       { alt: imageAlt(fields.alt, scope), style: fields.styles(scope) },
     );
   };
@@ -941,7 +1164,9 @@ let nodes = ({ bad }, { arr, obj, keys, expression, cellValue, visibleOf, styles
     );
     return (scope) => {
       if (hidden(visible, scope)) return null;
-      let out = [opt({ type: "split-start", role, slots: geometry }, { style: styles(scope) })];
+      let out = [
+        opt({ type: "split-start", role, path, slots: geometry }, { style: styles(scope) }),
+      ];
       for (let slot of slots) out.push(slot.render(scope));
       out.push({ type: "split-end" });
       return out;
@@ -997,8 +1222,23 @@ let nodes = ({ bad }, { arr, obj, keys, expression, cellValue, visibleOf, styles
  * @param {Nodes} nodes
  */
 let bands = (
-  { bad, runNames },
-  { arr, obj, keys, named, expression, visibleOf, columnsOf, takeOf, stylesOf, foldsOf, sortOf },
+  { bad, pin, runNames },
+  {
+    arr,
+    obj,
+    keys,
+    named,
+    expression,
+    visibleOf,
+    columnsOf,
+    takeOf,
+    rowStylesOf,
+    rowEntriesOf,
+    underRow,
+    foldRow,
+    foldsOf,
+    sortOf,
+  },
   { columnOf, itemsOf, totalOf },
 ) => {
   // Stacked items, one pass per row.
@@ -1014,30 +1254,71 @@ let bands = (
       }
     };
 
-  /** @type {(value: any) => { rowVisible: Eval | null, rowStyles: (scope: Scope) => any }} */
+  /** @type {(value: any) => { rowVisible: Eval | null, rowStyles: RowStyles }} */
   let rowLook = (value) => {
     if (value.row == null || !obj(value.row, "detail.row"))
-      return { rowVisible: null, rowStyles: NIL };
+      return { rowVisible: null, rowStyles: NO_ROW_STYLE };
     keys(value.row, ["visible", "style"], "detail.row");
     return {
       rowVisible: visibleOf(value.row, "detail.row"),
-      rowStyles: stylesOf(value.row, "detail.row", checkRowStyle),
+      rowStyles: rowStylesOf(value.row, "detail.row"),
     };
   };
   // The header-row box: `style` only, a different path from each column's
   // `header` cell. Absent when the table declares none.
-  /** @type {(value: any) => (scope: Scope) => any} */
+  /** @type {(value: any) => RowStyles} */
   let headerLook = (value) => {
-    if (value.header == null || !obj(value.header, "detail.header")) return NIL;
+    if (value.header == null || !obj(value.header, "detail.header")) return NO_ROW_STYLE;
     keys(value.header, ["style"], "detail.header");
-    return stylesOf(value.header, "detail.header", checkRowStyle);
+    return rowStylesOf(value.header, "detail.header");
+  };
+  // Which slot each column's header sits in -- the same invariant a total row's
+  // cells carry, walked positionally rather than summed because the diagnostic
+  // has to name the column it broke at. Read off the raw definitions, before
+  // any column is parsed, so `columnOf` can report its verdict in the column's
+  // own turn. Spans are read leniently: an unreadable one covers a single
+  // column and gets its own diagnostic when the column is parsed.
+  //
+  // `own` fills its own slot, `covered` is filled by a neighbour's span, `over`
+  // reaches past the last column, and everything after an `over` is
+  // `unreached` -- one broken span should not also report every column behind
+  // it as headerless.
+  // How many columns a definition's header claims, read leniently: a malformed
+  // column, a missing header and an unreadable span all claim one here, and
+  // each gets its own diagnostic when the column is parsed.
+  /** @type {(def: any) => number} */
+  let headerSpan = (def) => {
+    let header = record(def) ? def.header : null;
+    return record(header) ? spanValue(header.span) : 1;
+  };
+  /** @type {(slots: string[], from: number, to: number, slot: string) => void} */
+  let fill = (slots, from, to, slot) => {
+    for (let at = from; at < to; at++) slots[at] = slot;
+  };
+  /** @type {(defs: any[]) => string[]} */
+  let headerCover = (defs) => {
+    let slots = defs.map(() => "own");
+    let at = 0;
+    while (at < defs.length) {
+      let span = headerSpan(defs[at]);
+      if (at + span > defs.length) {
+        slots[at] = "over";
+        fill(slots, at + 1, defs.length, "unreached");
+        return slots;
+      }
+      fill(slots, at + 1, at + span, "covered");
+      at += span;
+    }
+    return slots;
   };
   /** @type {(value: any) => { defs: any[] | null, columns: any[] }} */
   let tableColumns = (value) => {
     let defs = arr(value.columns, "detail.columns", true);
-    if (defs && !defs.length) bad("detail.columns", "expected at least one column");
-    let columns = (defs || [])
-      .map((def, i) => columnOf(def, "detail.columns[" + i + "]"))
+    let list = defs || [];
+    if (defs && !list.length) bad("detail.columns", "expected at least one column");
+    let slots = headerCover(list);
+    let columns = list
+      .map((def, i) => columnOf(def, "detail.columns[" + i + "]", slots[i]))
       .filter((column) => column != null);
     checkShares(bad, columns, "detail.columns", "column");
     return { defs, columns };
@@ -1047,100 +1328,134 @@ let bands = (
     totals
       .map((def, i) => {
         let path = prefix + "[" + i + "]";
-        let cell = totalOf(def, path);
-        return cell && { cell, path };
+        let total = totalOf(def, path);
+        return total && { cell: total.cell, span: total.span, box: total.box, path };
       })
       .filter((entry) => entry != null);
   /** @type {(rows: any[] | null) => any[]} */
   let nonempty = (rows) => {
-    if (rows && !rows.length) bad("detail.total", "expected at least one total row");
+    if (rows && !rows.length) bad("detail.total.rows", "expected at least one total row");
     return rows || [];
   };
-  /**
-   * @type {(value: any, defs: any[] | null) =>
-   *   { styles: (scope: Scope) => any, visible: any, cells: any[] }[] | null}
-   */
-  let tableTotals = (value, defs) =>
-    value.total == null
-      ? null
-      : nonempty(arr(value.total, "detail.total", true)).map((def, r) =>
-          totalRowOf(def, "detail.total[" + r + "]", defs),
-        );
+  // The totals block is the one place a table's rows are authored as a list,
+  // so it is also the one that needs a level above them to say what belongs to
+  // the block rather than to a row: its `style` and `visible` are the header
+  // row's, one level out (docs/adr/0049).
+  /** @type {(value: any, defs: any[] | null) => TotalBlock} */
+  let tableTotals = (value, defs) => {
+    if (value.total == null || !obj(value.total, "detail.total")) return NO_TOTALS;
+    keys(value.total, ["style", "visible", "rows"], "detail.total");
+    let block = rowEntriesOf(value.total, "detail.total");
+    return {
+      visible: visibleOf(value.total, "detail.total"),
+      rows: nonempty(arr(value.total.rows, "detail.total.rows", true)).map((def, r) =>
+        totalRowOf(def, "detail.total.rows[" + r + "]", defs, block),
+      ),
+    };
+  };
+  // Read leniently: a cell whose span is unreadable, or which is not an object
+  // at all, covers one column here, and its own diagnostic comes from parsing
+  // it. Otherwise one mistake would report twice.
   /** @type {(cells: any[], defs: any[] | null) => boolean} */
-  let aligned = (cells, defs) => !defs || cells.length === defs.length;
+  let covering = (cells, defs) =>
+    !defs ||
+    cells.reduce((all, cell) => all + spanValue(record(cell) ? cell.span : null), 0) ===
+      defs.length;
   /** @type {(cells: any[] | null, defs: any[] | null, path: string) => any[]} */
   let counted = (cells, defs, path) => {
     if (!cells) return [];
-    if (!aligned(cells, defs)) bad(path + ".cells", "expected one cell per column");
+    if (!covering(cells, defs)) bad(path + ".cells", "expected cells covering every column");
     return cells;
   };
-  /**
-   * @type {(def: any, path: string, defs: any[] | null) =>
-   *   { styles: (scope: Scope) => any, visible: any, cells: any[] }}
-   */
-  let totalRowOf = (def, path, defs) => {
-    if (!obj(def, path)) return { styles: NIL, visible: null, cells: [] };
+  /** @type {(def: any, path: string, defs: any[] | null, block: RowEntries) => TotalRow} */
+  let totalRowOf = (def, path, defs, block) => {
+    if (!obj(def, path)) return { styles: foldRow(block), visible: null, cells: [], fan: [] };
     keys(def, ["cells", "style", "visible"], path);
     let cells = counted(arr(def.cells, path + ".cells", true), defs, path);
+    let styles = foldRow(underRow(block, rowEntriesOf(def, path)));
+    let mapped = mapTotals(cells, path + ".cells");
     return {
-      styles: stylesOf(def, path, checkRowStyle),
+      styles,
       visible: visibleOf(def, path),
-      cells: mapTotals(cells, path + ".cells"),
+      cells: mapped,
+      fan: mapped.map((entry) => boxReaching(styles.names, entry.box)),
     };
   };
   /**
    * @type {(rows: any[], scope: Scope, runners: RunnerSet, columns: any[],
-   *   rowVisible: Eval | null, rowStyles: (scope: Scope) => any) => Generator<any>}
+   *   rowVisible: Eval | null, rowStyles: RowStyles,
+   *   fan: (string[] | null)[]) => Generator<any>}
    */
-  function* tableRows(rows, scope, runners, columns, rowVisible, rowStyles) {
+  function* tableRows(rows, scope, runners, columns, rowVisible, rowStyles, fan) {
     for (let row of rows) {
       let scopeOfRow = runners.bind(scope, row);
-      if (!hidden(rowVisible, scopeOfRow))
-        yield opt(
-          {
-            type: "row",
-            cells: columns.map((column) =>
-              Object.assign(column.cell(scopeOfRow), { path: column.path }),
-            ),
-          },
-          { style: rowStyles(scopeOfRow), run: scopeOfRow.run },
-        );
+      if (hidden(rowVisible, scopeOfRow)) continue;
+      let cells = columns.map((column) =>
+        Object.assign(column.cell(scopeOfRow), { path: column.path }),
+      );
+      fanBox(rowStyles.box(scopeOfRow), cells, fan);
+      yield opt({ type: "row", cells }, { style: rowStyles.rest(scopeOfRow), run: scopeOfRow.run });
     }
   }
-  /**
-   * @type {(total: { styles: (scope: Scope) => any, visible: any, cells: any[] }[] | null,
-   *   scope: Scope) => Generator<any>}
-   */
+  // One cell that may cover several columns: its value against this scope, the
+  // path naming the definition behind it, and a `span` only when it covers more
+  // than one. The header row and the total rows are both authored as cells like
+  // this; a data row's are the columns' own and cannot span (SCHEMA.md,
+  // "Span"), which is why `tableRows` builds its own without a span at all.
+  /** @type {(cell: any, span: any, path: string, scope: Scope) => any} */
+  let spanCell = (cell, span, path, scope) =>
+    opt(Object.assign(cell(scope), { path }), { span: spanned(span) });
+  // One emitted total row. Its `styles` already carry the totals block's,
+  // composed in at compile time, so this is a row like any other.
+  /** @type {(row: TotalRow, scope: Scope) => any} */
+  let totalRow = (row, scope) => {
+    let cells = row.cells.map(({ cell, span, path }) => spanCell(cell, span, path, scope));
+    fanBox(row.styles.box(scope), cells, row.fan);
+    return opt({ type: "total-row", cells }, { style: row.styles.rest(scope) });
+  };
+  // A hidden block is the whole thing gone -- its rows are never reached, so
+  // nothing is evaluated and nothing votes on a column width, exactly as an
+  // absent `total` behaves.
+  /** @type {(total: TotalBlock, scope: Scope) => Generator<any>} */
   function* emitTotals(total, scope) {
-    if (!total) return;
-    for (let row of total) {
-      if (hidden(row.visible, scope)) continue;
-      yield opt(
-        {
-          type: "total-row",
-          cells: row.cells.map(({ cell, path }) => Object.assign(cell(scope), { path })),
-        },
-        { style: row.styles(scope) },
-      );
-    }
+    if (hidden(total.visible, scope)) return;
+    for (let row of total.rows) if (!hidden(row.visible, scope)) yield totalRow(row, scope);
   }
-  /** @type {(columns: any[], total: { styles: (scope: Scope) => any, visible: any, cells: any[] }[] | null, rowVisible: Eval | null, rowStyles: (scope: Scope) => any, headerStyles: (scope: Scope) => any) => Band} */
-  let tableBand = (columns, total, rowVisible, rowStyles, headerStyles) =>
-    function* (rows, scope, runners) {
-      yield opt(
-        {
-          type: "table-start",
-          path: "detail",
-          columns: columns.map((column) =>
-            opt({ header: column.header(scope), path: column.path }, { width: column.width }),
-          ),
-        },
-        { style: headerStyles(scope) },
+  /** @type {(columns: any[], total: TotalBlock, rowVisible: Eval | null, rowStyles: RowStyles, headerStyles: RowStyles) => Band} */
+  let tableBand = (columns, total, rowVisible, rowStyles, headerStyles) => {
+    // Which of each row box reaches which cell, settled once per table over
+    // the names both sides declared -- so nothing at render reads a resolved
+    // object to find out who owns a border side (docs/adr/0056).
+    let rowFan = columns.map((column) => boxReaching(rowStyles.names, column.box));
+    let headers = columns.filter((column) => column.header);
+    let headerFan = headers.map((column) => boxReaching(headerStyles.names, column.header.box));
+    return function* (rows, scope, runners) {
+      // The header row, built once here rather than reconstructed by every
+      // consumer from a per-column `header` (docs/adr/0053). A covered column
+      // declares none, so this is fewer cells than columns whenever one spans
+      // -- and a header cell carries its column's `path`, as a row cell does,
+      // so every rendered cell can name the definition behind it.
+      let cells = headers.map((column) =>
+        spanCell(column.header.cell, column.header.span, column.path, scope),
       );
-      yield* tableRows(rows, scope, runners, columns, rowVisible, rowStyles);
+      // The header row's box lands on its cells, exactly as a data row's does,
+      // which is why what is left of the block rides beside them.
+      fanBox(headerStyles.box(scope), cells, headerFan);
+      // `columns` is what is left once the header row is its own: the
+      // geometry, one entry per column, carrying a `width` share when the
+      // document authored one.
+      let cols = columns.map((column) => opt({}, { width: column.width }));
+      yield {
+        type: "table-start",
+        path: "detail",
+        header: opt({ cells }, { style: headerStyles.rest(scope) }),
+        columns: cols,
+      };
+      yield* tableRows(rows, scope, runners, columns, rowVisible, rowStyles, rowFan);
       yield* emitTotals(total, scope);
       yield { type: "table-end" };
     };
+  };
   /** @type {(value: any) => Band} */
   let tableOf = (value) => {
     keys(value, ["header", "row", "columns", "total"], "detail");
@@ -1154,6 +1469,7 @@ let bands = (
   // `{ columns, total }` object is a real table.
   /** @type {(value: any) => Band} */
   let detailOf = (value) => {
+    pin.body(value, "detail");
     if (Array.isArray(value) || value == null) return itemsBand(itemsOf(value, "detail", "detail"));
     if (!record(value)) {
       bad("detail", "expected an array of items or a table object");
@@ -1207,7 +1523,11 @@ let bands = (
     }
     groupScope[ctx.name] = handle;
     let rows = (ctx.sort ? ctx.sort(groupRows, groupScope) : groupRows).slice(0, ctx.take);
-    return { groupScope, aggregates: applyAggs(ctx.aggs, rows, groupScope, handle), rows };
+    return {
+      groupScope,
+      aggregates: applyAggs(ctx.aggs, rows, groupScope, handle),
+      rows,
+    };
   };
   /** @type {(ctx: any) => Band} */
   let groupWalk = (ctx) =>
@@ -1262,9 +1582,9 @@ let bands = (
       by,
       sort: sortOf(def.sort, path + ".sort"),
       take: takeOf(def.take, path + ".take"),
-      aggs: foldsOf(def.aggregates, path + ".aggregates", AGG, new Set(["key"])),
-      running: foldsOf(def.run, path + ".run", RUN, null, runNames),
-      header: itemsOf(def.header, path + ".header", "group-header"),
+      aggs: foldsOf(def.aggregates, path + ".aggregates", "aggregate", new Set(["key"])),
+      running: foldsOf(def.run, path + ".run", "run", null, runNames),
+      header: pinBand(def.header, path + ".header"),
       footer: itemsOf(def.footer, path + ".footer", "group-footer"),
       inner: bandOf(defs, index + 1, detail, columned || columns != null),
       name: def.name,
@@ -1276,6 +1596,15 @@ let bands = (
     });
   };
 
+  // A group's header, offered to the band-height guard on the way past: the
+  // chain compiles outermost first, so the first one that occupies is the band
+  // under a pinned box (./band-height.js).
+  /** @type {(value: any, path: string) => (scope: Scope) => Generator<any>} */
+  let pinBand = (value, path) => {
+    pin.body(value, path);
+    return itemsOf(value, path, "group-header");
+  };
+
   // The band chain, outermost group first: each group partitions its rows and
   // recurses; the detail band sits at the leaf.
   /** @type {(defs: any[], index: number, detail: any, columned?: boolean) => Band} */
@@ -1319,25 +1648,22 @@ let selectOf = (schema, bad, attempt, options) => {
 };
 /** @type {(value: any, path: string, expression: any) => any} */
 let maybeExpr = (value, path, expression) => (value != null ? expression(value, path) : null);
-/** @type {(n: any) => boolean} */
-let posPts = (n) => typeof n === "number" && Number.isFinite(n) && n > 0;
+
 /** @type {(n: any) => boolean} */
 let padPts = (n) => typeof n === "number" && Number.isFinite(n) && n >= 0;
 /** @type {(height: any, bad: any) => number | null} */
 let headerHeightOf = (height, bad) => {
   if (height == null) bad("header.height", "required");
-  else if (!posPts(height)) bad("header.height", "expected a positive number of points");
-  return posPts(height) ? height : null;
+  else if (!positivePts(height)) bad("header.height", "expected a positive number of points");
+  return positivePts(height) ? height : null;
 };
-/** @type {(itemsOf: any) => { items: any, height: number | null }} */
-let emptyHeader = (itemsOf) => ({ items: itemsOf(null, "header", "report-header"), height: null });
 /** @type {(value: any, keys: any, itemsOf: any, bad: any) => { items: any, height: number | null }} */
 let reportHeaderOf = (value, keys, itemsOf, bad) => {
   if (value == null || Array.isArray(value))
     return { items: itemsOf(value, "header", "report-header"), height: null };
   if (!record(value)) {
     bad("header", "expected an array of items or { height, items }");
-    return emptyHeader(itemsOf);
+    return { items: itemsOf(null, "header", "report-header"), height: null };
   }
   keys(value, ["height", "items"], "header");
   return {
@@ -1364,36 +1690,6 @@ let pageBands = (schema, obj, keys, itemsOf, bad) => {
   };
 };
 
-/** @type {(def: any) => boolean} */
-let shown = (def) => !(def && def.visible === false);
-/** @type {(list: any, path: string) => [any, string] | null} */
-let firstOccupying = (list, path) => {
-  if (!Array.isArray(list)) return null;
-  let i = list.findIndex(shown);
-  return i < 0 ? null : [list[i], path + "[" + i + "]"];
-};
-/** @type {(schema: any) => any} */
-let firstGroupHeader = (schema) => {
-  let groups = schema.groups;
-  return Array.isArray(groups) && groups[0] ? groups[0].header : null;
-};
-/** @type {(schema: any) => [any, string] | null} */
-let nextAfterHeader = (schema) =>
-  firstOccupying(firstGroupHeader(schema), "groups[0].header") ||
-  firstOccupying(schema.detail, "detail");
-/** @type {(n: any) => boolean} */
-let nonzeroLead = (n) => typeof n === "number" && n !== 0;
-/** @type {(next: [any, string], bad: any) => void} */
-let refuseLiteralLead = (next, bad) => {
-  if (nonzeroLead(next[0].style?.spaceBefore))
-    bad(next[1] + ".style.spaceBefore", "must be 0 after a height-declared header");
-};
-/** @type {(schema: any, headerHeight: number | null, bad: any) => void} */
-let refusePinnedLead = (schema, headerHeight, bad) => {
-  if (headerHeight == null) return;
-  let next = nextAfterHeader(schema);
-  if (next) refuseLiteralLead(next, bad);
-};
 /** @type {(headerHeight: number | null, schema: any, bad: any) => void} */
 let needPinnedMargin = (headerHeight, schema, bad) => {
   if (headerHeight != null && schema.page?.margin == null)
@@ -1416,7 +1712,7 @@ let needPinnedMargin = (headerHeight, schema, bad) => {
  *   render may traverse, never what this descent reports.
  */
 let traverse = (
-  { add, bad, attempt, runNames },
+  { add, bad, attempt, pin, runNames },
   { arr, obj, keys, named, expression, columnsOf, takeOf, foldsOf, sortOf, stylesOf },
   { itemsOf },
   { bandOf },
@@ -1456,8 +1752,8 @@ let traverse = (
   let where = maybeExpr(schema.where, "where", expression);
   let sort = sortOf(schema.sort, "sort");
   let take = takeOf(schema.take, "take");
-  let aggs = foldsOf(schema.aggregates, "aggregates", AGG, new Set(["params", "input"]));
-  let running = foldsOf(schema.run, "run", RUN, null, runNames);
+  let aggs = foldsOf(schema.aggregates, "aggregates", "aggregate", new Set(["params", "input"]));
+  let running = foldsOf(schema.run, "run", "run", null, runNames);
   // The report default: one style block for the whole document, narrowed to
   // the declarations a typeface is made of. It resolves once per render in
   // report scope rather than per node, which is why it crosses the seam as a
@@ -1465,9 +1761,14 @@ let traverse = (
   // nothing here allocates per cell (docs/adr/0033).
   let style = stylesOf(schema, "", checkReportStyle);
   let { items: header, height: headerHeight } = reportHeaderOf(schema.header, keys, itemsOf, bad);
-  refusePinnedLead(schema, headerHeight, bad);
+  // A declared height arms the band-height guard, which every band below is
+  // offered as the descent reaches it (./band-height.js).
+  pin.arm(headerHeight);
   // Null when undeclared, so the render decides on the compiled band rather
-  // than reading `schema.empty` a second time from outside the traversal.
+  // than reading `schema.empty` a second time from outside the traversal. The
+  // guard is offered it here, where the traversal already holds it: `empty`
+  // replaces the body rather than following it, so it is judged on its own.
+  pin.instead(schema.empty, "empty");
   let empty = maybeItems(schema.empty, "empty", "empty", itemsOf);
   let columns = columnsOf(schema.columns, "columns");
   let band = bandOf(arr(schema.groups, "groups") || [], 0, schema.detail, columns != null);
@@ -1510,7 +1811,7 @@ let traverse = (
 export let plan = (schema, funcs, options) => {
   let state = planState(schema, funcs);
   let prim = primitives(state);
-  let read = readers(state, prim);
+  let read = readers(state, prim, options);
   let node = nodes(state, read);
   let band = bands(state, read, node);
   return {