quario 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -7,6 +7,55 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-09-05
+
+### Added
+
+- **`STYLE_NAMES`**, every name in the style vocabulary as a read-only list,
+  in the order the specification's table lists them. A tool that offers the
+  vocabulary — the editor's style rail — reads it from here instead of
+  carrying a copy that has to learn each new name.
+- **`span` lets a cell cover several table columns**, so a label reaches across
+  them instead of being pushed sideways by empty cells. A literal positive
+  integer; absent is 1. It is legal on the two cells a document writes: a
+  column's `header`, where the columns it covers omit their own `header`, and a
+  total row's cells, whose spans must sum to the column count exactly. A data
+  row's cells are the columns' own, so there is no cell there to carry one — a
+  line that runs across the table is a `split` item below it. A span covers and
+  does not vote: a cell over more than one column has no say in their widths,
+  and a column nothing votes on takes the cell-padding floor.
+- **`valign`** joins the style vocabulary: `"top"`, `"middle"` or `"bottom"`,
+  a literal or an `=` expression like `align`. It is legal exactly where a box
+  is taller than its content asked for — table cells, headers, totals, `row`,
+  and split slots, text or image — and a definition error on a stacked item and
+  on a band image, whose boxes have no such slack. A row's or a split's layers
+  under its cells' or slots' own. Undeclared is not a declaration: each target
+  keeps its own default.
+
+### Changed
+
+- **A table row's `style` now resolves onto that row's cells**, the box
+  included, instead of meaning something different on every output. Before,
+  padding and border on `detail.header`, `detail.row` or a total row's `style`
+  reached no cell at all: a fragment dropped them, a worksheet turned them into
+  an edge on each cell, and a page drew one box around the row. Now they layer
+  under each cell's own, the way `bold` and `valign` on a row already did, so
+  one declaration means one thing everywhere.
+  What this makes possible is declining the cell padding a row at a time:
+  `"paddingTop": 0, "paddingBottom": 0` on `detail.row` sets the pitch for
+  every data row, where before it had to be written on each cell.
+  Two things move for documents that already declared a box on a row.
+  A row's `borderLeft` is now an edge on each of the row's cells rather than
+  one at the row's outer left — write it on the first column's cells to get the
+  single edge back. And a row's border now occupies height, as a cell's border
+  always has, so a bordered row is taller by its border's width.
+  A border side is won whole by the cell: a cell naming any of that side's
+  three keys takes the side entirely, so a cell that failed soft on one name
+  does not inherit the row's other two.
+  On the event stream, a `row`, `total-row` or `table-start` `style` now
+  carries only what layers by ordinary means, and a row whose whole block was
+  box carries no `style` at all.
+
 ## [0.4.0] - 2026-09-03
 
 ### Changed

package/lib/index.d.ts

@@ -87,6 +87,12 @@ export interface StyleDeclarations extends BoxDeclarations {
   background?: ExpressionValue<string>;
   /** Horizontal alignment within the cell. */
   align?: ExpressionValue<Align>;
+  /**
+   * Vertical alignment within a box taller than its content: a table cell or
+   * row, a split slot (text or image). A definition error on a stacked item
+   * and on a band image, whose boxes have no such slack.
+   */
+  valign?: ExpressionValue<VAlign>;
   /** How a number or date is presented. Locale stays on the instance. */
   format?: ExpressionValue<FormatKind>;
   /** Blank space before this item, in points. */
@@ -104,6 +110,7 @@ export interface SortKey {
 export type CellValue = string;
 
 export type Align = "left" | "center" | "right";
+export type VAlign = "top" | "middle" | "bottom";
 export type FormatKind = "number" | "currency" | "percent" | "date";
 
 export interface Cell {
@@ -185,10 +192,19 @@ export interface TableHeader {
   value: CellValue;
   /** Literal only — never an expression. */
   style?: StyleDeclarations;
+  /**
+   * How many columns this header covers — a literal integer >= 1, never an
+   * expression; absent is 1. The columns it covers omit their own `header`.
+   */
+  span?: number;
 }
 
 export interface TableColumn extends Cell {
-  header: string | TableHeader;
+  /**
+   * Absent exactly when a neighbour's header `span` covers this column: every
+   * column's header slot is filled once, by its own or by a span.
+   */
+  header?: string | TableHeader;
   /** Column width as a percentage of the table width (0 < width <= 100). */
   width?: number;
 }
@@ -198,8 +214,20 @@ export interface TableRow {
   style?: StyleDeclarations;
 }
 
+/**
+ * One cell of a total row: an ordinary cell, plus the columns it covers. The
+ * spans in a row must sum to the column count exactly.
+ */
+export type TotalCell = Cell & {
+  /**
+   * How many columns this cell covers — a literal integer >= 1, never an
+   * expression; absent is 1.
+   */
+  span?: number;
+};
+
 export interface TotalRow {
-  cells: [Cell, ...Cell[]];
+  cells: [TotalCell, ...TotalCell[]];
   visible?: ExpressionValue<boolean>;
   style?: StyleDeclarations;
 }
@@ -357,6 +385,11 @@ export type Token = LiteralToken | ValueToken;
 export interface EventCell {
   tokens: Token[];
   style?: Record<string, unknown>;
+  /**
+   * How many columns this cell covers, present only when more than one: a
+   * span of 1 is the absence of one and never reaches the stream.
+   */
+  span?: number;
   /**
    * The definition's schema path, on cells that belong to one: a `row` cell
    * carries its column's (`detail.columns[i]`), a `total-row` cell its
@@ -490,7 +523,8 @@ export interface TableStartEvent {
   type: "table-start";
   /** Always `detail` — the table definition's schema path. */
   path: string;
-  columns: { header: EventCell; path: string; width?: number }[];
+  /** One entry per column. `header` is absent when a neighbour's span covers it. */
+  columns: { header?: EventCell; path: string; width?: number }[];
   /** The header-row box from `detail.header`, when declared. */
   style?: Record<string, unknown>;
 }
@@ -721,3 +755,10 @@ export function typed(
  * one: the question is whose band a role names, not what a walk can hand over.
  */
 export function isReportBand(role: string | undefined): boolean;
+
+/**
+ * Every name in the closed style vocabulary, in the order SCHEMA.md's table
+ * lists them. A tool that offers the vocabulary imports this rather than
+ * keeping a copy.
+ */
+export const STYLE_NAMES: readonly string[];

package/lib/index.js

@@ -25,6 +25,7 @@ import { opt } from "./stream.js";
 // imports them from the package, not from a file inside it.
 export { breathe, display, isReportBand, text, typed, walk } from "./stream.js";
 export { format } from "./format.js";
+export { STYLE_NAMES } from "./style.js";
 export { isDiagnostic } from "./locate.js";
 
 /** @typedef {import("./scope.js").Scope} Scope */

package/lib/license.js

@@ -11,7 +11,7 @@
 // reassigns them. A key is valid for every version released inside its window
 // (LICENSE section 7), so validity compares ISO date strings and never reads
 // a clock — accepted output stays accepted.
-let RELEASE = "2026-09-03"; // x-release-please-date
+let RELEASE = "2026-09-05"; // x-release-please-date
 // The verifying half of the signing pair: the 65-byte uncompressed P-256
 // point, base64url. The private half never enters the repo;
 // scripts/license/sign.mjs mints keys against it.

package/lib/plan.js

@@ -54,8 +54,11 @@ import {
   checkReportStyle,
   checkRowStyle,
   checkSlotImageStyle,
+  checkItemStyle,
   checkSlotStyle,
   checkStyle,
+  fanBox,
+  isBoxName,
 } from "./style.js";
 
 // Tolerance on the column-width sum. Widths are literal numbers an author may
@@ -67,11 +70,29 @@ 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, rest: (scope: Scope) => any }} RowStyles */
+/** @type {RowStyles} */
+let NO_ROW_STYLE = { box: NIL, rest: NIL };
 /** @type {any} */
 let EMPTY = () => [];
 // What `$.params` reads when a report declares none.
 let NONE = Object.freeze({});
 
+// 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 {(value: any) => boolean} */
 let isExpr = (value) => typeof value === "string" && value[0] === "=";
 /** @type {(from: Iterable<string>, into: Set<string>) => void} */
@@ -564,21 +585,56 @@ let readers = ({ bad, attempt }, { prop, cell, parseFold }) => {
     for (let [name, value] of entries) style[name] = value(scope);
     return style;
   };
-  /** @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 {(block: any, entries: [string, Eval][]) => (scope: Scope) => any} */
+  let folded = (block, entries) => {
     if (!entries.length) return NIL;
     let resolve = styleFn(entries);
-    if (isComputed(block)) return resolve;
+    if (entries.some(([name]) => isExpr(block[name]))) return resolve;
     let constant = Object.freeze(resolve({}));
     return () => constant;
   };
+  /**
+   * @type {(block: any, path: string, check: (name: string, value: any) => string | null)
+   *   => [string, Eval][]}
+   */
+  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 compileStyles = (block, path, check) => folded(block, styleEntries(block, path, check));
+  // 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 {(block: any, path: string, check: (name: string, value: any) => string | null)
+   *   => RowStyles}
+   */
+  let compileRowStyles = (block, path, check) => {
+    let entries = styleEntries(block, path, check);
+    return {
+      box: folded(
+        block,
+        entries.filter(([name]) => isBoxName(name)),
+      ),
+      rest: folded(
+        block,
+        entries.filter(([name]) => !isBoxName(name)),
+      ),
+    };
+  };
   /**
    * @type {(def: any, path: string, check?: (name: string, value: any) => string | null)
    *   => (scope: Scope) => any}
@@ -589,6 +645,14 @@ let readers = ({ bad, attempt }, { prop, cell, parseFold }) => {
     if (block == null || !obj(block, stylePath)) return NIL;
     return compileStyles(block, stylePath, check);
   };
+  /** The same, for the three blocks that sit on a table row. */
+  /** @type {(def: any, path: string) => RowStyles} */
+  let rowStylesOf = (def, path) => {
+    let block = def.style;
+    let stylePath = pathTo(path, "style");
+    if (block == null || !obj(block, stylePath)) return NO_ROW_STYLE;
+    return compileRowStyles(block, stylePath, checkRowStyle);
+  };
   // 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} */
@@ -703,6 +767,7 @@ let readers = ({ bad, attempt }, { prop, cell, parseFold }) => {
     columnsOf,
     takeOf,
     stylesOf,
+    rowStylesOf,
     cellValue,
     foldsOf,
     sortOf,
@@ -738,17 +803,53 @@ let nodes = ({ bad }, { arr, obj, keys, expression, cellValue, visibleOf, styles
     return cellShape(tpl, visible, stylesOf(def, path, checkCellStyle));
   };
 
+  /** @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 }}
+   */
   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 };
     if (!record(def)) {
       bad(path, "expected a template string or object");
-      return cellShape(EMPTY, null, NIL);
+      return { cell: cellShape(EMPTY, null, NIL), span: 1 };
     }
-    keys(def, ["value", "style"], path);
-    return cellOf(def, path);
+    keys(def, ["value", "style", "span"], path);
+    return { cell: 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 } | 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,11 +860,11 @@ 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);
@@ -773,11 +874,14 @@ let nodes = ({ bad }, { arr, obj, keys, expression, cellValue, visibleOf, styles
     return { header, cell: cellShape(tpl, visible, styles), 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 } | 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 { cell: 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 +897,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.
@@ -998,7 +1102,7 @@ let nodes = ({ bad }, { arr, obj, keys, expression, cellValue, visibleOf, styles
  */
 let bands = (
   { bad, runNames },
-  { arr, obj, keys, named, expression, visibleOf, columnsOf, takeOf, stylesOf, foldsOf, sortOf },
+  { arr, obj, keys, named, expression, visibleOf, columnsOf, takeOf, rowStylesOf, foldsOf, sortOf },
   { columnOf, itemsOf, totalOf },
 ) => {
   // Stacked items, one pass per row.
@@ -1014,30 +1118,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,8 +1192,8 @@ 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, path };
       })
       .filter((entry) => entry != null);
   /** @type {(rows: any[] | null) => any[]} */
@@ -1058,7 +1203,7 @@ let bands = (
   };
   /**
    * @type {(value: any, defs: any[] | null) =>
-   *   { styles: (scope: Scope) => any, visible: any, cells: any[] }[] | null}
+   *   { styles: RowStyles, visible: any, cells: any[] }[] | null}
    */
   let tableTotals = (value, defs) =>
     value.total == null
@@ -1066,76 +1211,91 @@ let bands = (
       : nonempty(arr(value.total, "detail.total", true)).map((def, r) =>
           totalRowOf(def, "detail.total[" + r + "]", defs),
         );
+  // 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[] }}
+   *   { styles: RowStyles, visible: any, cells: any[] }}
    */
   let totalRowOf = (def, path, defs) => {
-    if (!obj(def, path)) return { styles: NIL, visible: null, cells: [] };
+    if (!obj(def, path)) return { styles: NO_ROW_STYLE, visible: null, cells: [] };
     keys(def, ["cells", "style", "visible"], path);
     let cells = counted(arr(def.cells, path + ".cells", true), defs, path);
     return {
-      styles: stylesOf(def, path, checkRowStyle),
+      styles: rowStylesOf(def, path),
       visible: visibleOf(def, path),
       cells: mapTotals(cells, path + ".cells"),
     };
   };
   /**
    * @type {(rows: any[], scope: Scope, runners: RunnerSet, columns: any[],
-   *   rowVisible: Eval | null, rowStyles: (scope: Scope) => any) => Generator<any>}
+   *   rowVisible: Eval | null, rowStyles: RowStyles) => Generator<any>}
    */
   function* tableRows(rows, scope, runners, columns, rowVisible, rowStyles) {
     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);
+      yield opt({ type: "row", cells }, { style: rowStyles.rest(scopeOfRow), run: scopeOfRow.run });
     }
   }
   /**
-   * @type {(total: { styles: (scope: Scope) => any, visible: any, cells: any[] }[] | null,
+   * @type {(total: { styles: RowStyles, visible: any, cells: any[] }[] | null,
    *   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) },
+      let cells = row.cells.map(({ cell, span, path }) =>
+        opt(Object.assign(cell(scope), { path }), { span: spanned(span) }),
       );
+      fanBox(row.styles.box(scope), cells);
+      yield opt({ type: "total-row", cells }, { style: row.styles.rest(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} */
+  /** @type {(columns: any[], total: { styles: RowStyles, visible: any, cells: any[] }[] | null, rowVisible: Eval | null, rowStyles: RowStyles, headerStyles: RowStyles) => Band} */
   let tableBand = (columns, total, rowVisible, rowStyles, headerStyles) =>
     function* (rows, scope, runners) {
+      // A covered column carries no `header` at all: the header row is the
+      // cells the columns declare, which is fewer than the columns whenever
+      // one spans. A consumer that reads no `span` still gets one cell per
+      // uncovered column, which is the shape this had before spans existed.
+      let cols = columns.map((column) =>
+        opt(
+          {},
+          {
+            header:
+              column.header &&
+              opt(column.header.cell(scope), { span: spanned(column.header.span) }),
+            path: column.path,
+            width: column.width,
+          },
+        ),
+      );
+      // The header-row box fans onto the cells that are there, which for the
+      // same reason is fewer than the columns whenever one spans. The list is
+      // built only when there is a box to put on it.
+      let box = headerStyles.box(scope);
+      if (box) fanBox(box, cols.map((column) => column.header).filter(Boolean));
       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: "table-start", path: "detail", columns: cols },
+        { style: headerStyles.rest(scope) },
       );
       yield* tableRows(rows, scope, runners, columns, rowVisible, rowStyles);
       yield* emitTotals(total, scope);
@@ -1329,15 +1489,13 @@ let headerHeightOf = (height, bad) => {
   else if (!posPts(height)) bad("header.height", "expected a positive number of points");
   return posPts(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 {

package/lib/stream.js

@@ -38,8 +38,6 @@ let asDeclared = (value, kind) => (kind === "date" ? reviveDate(value) : undefin
 let RFC3339 =
   /^(\d{4})-(\d{2})-(\d{2})(?:T(\d{2}):(\d{2}):(\d{2})(?:\.\d+)?(?:Z|[+-](\d{2}):(\d{2})))?$/;
 
-/** @type {(year: string, month: string) => number} */
-let monthLength = (year, month) => new Date(Date.UTC(+year, +month, 0)).getUTCDate();
 // An absent group is the timestamp half of an optional match, not a breach.
 /** @type {(bound: [string | undefined, number, number]) => boolean} */
 let within = ([n, lo, hi]) => n === undefined || (+n >= lo && +n <= hi);
@@ -69,7 +67,7 @@ export let reviveDate = (value) => {
   /** @type {[string | undefined, number, number][]} */
   let bounds = [
     [month, 1, 12],
-    [day, 1, monthLength(year, month)],
+    [day, 1, new Date(Date.UTC(+year, +month, 0)).getUTCDate()],
     [hour, 0, 23],
     [minute, 0, 59],
     [second, 0, 59],

package/lib/style.js

@@ -1,12 +1,21 @@
 /**
- * The closed style vocabulary, as the traversal checks it: target-neutral names
- * with typed literal values. Unknown names and mistyped literals are definition
- * errors; `=` results stay lenient at render. Each target maps these names to
- * its own formatting model, and nothing here knows about any of them.
+ * The closed style vocabulary — target-neutral names with typed literal values —
+ * and the resolutions the event stream is defined in terms of. Two things, and
+ * the split between them is the file's organising claim.
  *
- * `finite`/`HEX` are restated per target on purpose: those coercions are each
- * target's own edge, never shared engine code — unlike the stream rules
- * (`typed`), which every target reads from `./stream.js`.
+ * The **checks** are what the traversal runs: unknown names and mistyped
+ * literals are definition errors; `=` results stay lenient at render.
+ *
+ * The **resolutions** are what a declaration means before any target sees it.
+ * A row's box is the one there is (SCHEMA.md, "Style declarations"): it says
+ * what the document means rather than what a surface paints, so every target
+ * is handed the answer instead of reaching its own. That is the same line
+ * `./stream.js` sits on, and the opposite side of it from `finite`/`HEX`,
+ * which are restated per target on purpose because a coercion is each target's
+ * own edge.
+ *
+ * Past those, each target maps these names to its own formatting model, and
+ * nothing here knows about any of them.
  */
 /** @type {(value: any) => boolean} */
 let finite = (value) => typeof value === "number" && Number.isFinite(value);
@@ -19,6 +28,8 @@ let spec = (msg, ok) => ({ ok, msg });
 let COLOR = spec("expected a #rgb or #rrggbb color", isHex);
 let FLAG = spec("expected a boolean", (value) => typeof value === "boolean");
 let ALIGNMENTS = ["left", "center", "right"];
+// "middle", not "center": that word is already the horizontal one.
+let VALIGNMENTS = ["top", "middle", "bottom"];
 let LINES = ["solid", "dashed", "dotted"];
 let SIDES = ["Top", "Right", "Bottom", "Left"];
 let BORDER_PARTS = ["Width", "Style", "Color"];
@@ -49,6 +60,7 @@ let STYLES = {
   color: COLOR,
   background: COLOR,
   align: spec("expected left, center, or right", (value) => ALIGNMENTS.includes(value)),
+  valign: spec("expected top, middle, or bottom", (value) => VALIGNMENTS.includes(value)),
   format: spec("expected number, currency, percent, or date", (value) => FORMATS.includes(value)),
 };
 let FORMATS = ["number", "currency", "percent", "date"];
@@ -73,6 +85,27 @@ for (let name of FLOW) {
   STYLES[name] = POINTS;
   IMAGE_STYLES.push(name);
 }
+// The vocabulary as a list, in the order SCHEMA.md's table reads it: the text
+// names, the flow, then the box one part at a time across the four sides. A
+// tool that offers the vocabulary (the editor's style rail) imports this
+// rather than keeping a copy that has to be told about every new name.
+/** @type {readonly string[]} */
+// The box half of the vocabulary, generated once from the same two tables the
+// checks read. `isBoxName` is the only place the question "does this name
+// belong to the box?" is answered, so a name that does not start with
+// `padding` or `border` could join without every asker being told separately.
+let BOX_NAMES = [
+  ...SIDES.map((side) => "padding" + side),
+  ...BORDER_PARTS.flatMap((part) => SIDES.map((side) => "border" + side + part)),
+];
+let BOX = new Set(BOX_NAMES);
+/** @type {(name: string) => boolean} */
+export let isBoxName = (name) => BOX.has(name);
+export let STYLE_NAMES = Object.freeze([
+  ...Object.keys(STYLES).filter((name) => !FLOW.includes(name) && !isBoxName(name)),
+  ...FLOW,
+  ...BOX_NAMES,
+]);
 // One check for both the validating traversal and the compile path: an error
 // message for a declaration, or null when it is acceptable (expressions defer
 // to render).
@@ -150,9 +183,80 @@ let withoutFlow = (check, subject) => withoutNames(FLOW_NAMES, check, subject);
 
 export let checkCellStyle = withoutFlow(checkStyle, "a table cell");
 export let checkSlotStyle = withoutFlow(checkStyle, "a split slot");
-export let checkSlotImageStyle = withoutFlow(checkImageStyle, "a split slot");
+// `valign` is legal exactly where a box has height it did not ask for
+// (CONTEXT.md "Box": slack). A slot's box is the split's height, so a slot --
+// text or image -- reads it; a band image's box is its own, so it does not.
+// That is the one name an image accepts in a slot and nowhere else, the same
+// shape of reason `width` reaches an item only there (docs/adr/0029).
+let SLOT_IMAGE_STYLES = [...IMAGE_STYLES, "valign"];
+export let checkSlotImageStyle = withoutFlow(
+  narrowed(SLOT_IMAGE_STYLES, "an image"),
+  "a split slot",
+);
+// A stacked text item's box is exactly its content and padding: no slack, so
+// `valign` is refused rather than left unread.
+/** @type {Record<string, true>} */
+let STACKED_NAMES = { valign: true };
+export let checkItemStyle = withoutNames(STACKED_NAMES, checkStyle, "a stacked item");
 // A row box has no cell value, so `format` is refused there the way flow
 // spacing is — it is a presentation of a value, not of a band of cells.
 /** @type {Record<string, true>} */
 let ROW_NAMES = { ...FLOW_NAMES, format: true };
 export let checkRowStyle = withoutNames(ROW_NAMES, checkStyle, "a table row");
+
+// --- resolution --------------------------------------------------------------
+
+// A row's `style` resolves onto its cells (SCHEMA.md, "Style declarations").
+// The box is the half that cannot arrive any other way: a table row is not a
+// box on any surface -- not a `<tr>`, not a worksheet row, not a band of the
+// PDF's own -- so it is resolved here, once, and no target is left to have an
+// opinion about it. Every other declaration on a row reaches its cells by the
+// layering each target already does, which is why only the box moves.
+//
+// Which names are the box is decided where the block is compiled, not here: a
+// literal row style is partitioned once per table rather than once per row.
+// What is left for render is the per-cell layering below.
+
+// The three names of each border side, built once. `layer` reaches for them
+// per cell, and rebuilding twelve strings per cell was most of what this cost.
+/** @type {Record<string, string[]>} */
+let BORDER_NAMES = Object.fromEntries(
+  SIDES.map((side) => [side, BORDER_PARTS.map((part) => "border" + side + part)]),
+);
+
+/** @type {(block: any, side: string) => boolean} */
+let ownsSide = (block, side) => BORDER_NAMES[side].some((name) => Object.hasOwn(block, name));
+
+// The spread has already written every name the cell declared, so taking a
+// side is dropping what is left of the row's: the names of that side the cell
+// did not name itself.
+/** @type {(out: any, over: any, side: string) => void} */
+let takeSide = (out, over, side) => {
+  for (let name of BORDER_NAMES[side]) if (!Object.hasOwn(over, name)) delete out[name];
+};
+
+// A border side is won whole by the cell: a cell that named any of the three
+// keys takes that side entirely, so a cell that failed-soft on one name does
+// not pick up the row's other two and become a stroke nobody declared. Only
+// the sides the row's box actually declares can be taken from it, so the
+// caller settles which those are once and hands them down.
+/** @type {(under: any, over: any, sides: string[]) => any} */
+let layer = (under, over, sides) => {
+  if (!over) return under;
+  let out = { ...under, ...over };
+  for (let side of sides) if (ownsSide(over, side)) takeSide(out, over, side);
+  return out;
+};
+
+/**
+ * Resolve a row's box onto the row's cells. The cells are written in place:
+ * both they and the box were built for this one event and nothing else holds
+ * them yet. A row that declares no box is the common case and costs one test.
+ *
+ * @type {(box: any, cells: any[]) => void}
+ */
+export let fanBox = (box, cells) => {
+  if (!box) return;
+  let sides = SIDES.filter((side) => ownsSide(box, side));
+  for (let cell of cells) cell.style = layer(box, cell.style, sides);
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "quario",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "A tiny, runtime-neutral report engine — in the makings, not yet released",
   "homepage": "https://getquario.com",
   "license": "SEE LICENSE IN LICENSE",
@@ -51,7 +51,7 @@
         "sjabloon",
         "padvinder"
       ],
-      "limit": "10 kB"
+      "limit": "11 kB"
     }
   ],
   "engines": {