@quario/docx 0.1.0

package/lib/style.js

@@ -0,0 +1,270 @@
+/**
+ * This target's reading of the closed style vocabulary — the counterpart of the
+ * CSS table in the HTML target, the points-and-colours module in the layout,
+ * and `style.js` in the XLSX target. Declarations are lenient at render: a
+ * value of the wrong shape contributes nothing rather than reaching the
+ * document.
+ *
+ * Everything here is a property *string*, in the order the schema fixes.
+ * `CT_RPr`, `CT_PPrBase`, `CT_TcPr` and the border containers are sequences,
+ * not bags, and a reader handed their children out of order may offer to repair
+ * the file — so the order below is the contract, and the one place to check
+ * when a declaration is added.
+ *
+ * `finite`/`HEX` are restated per target on purpose: the coercions are each
+ * target's own edge, never shared engine code.
+ */
+
+import { twips } from "./page.js";
+import { esc } from "./xml.js";
+
+let HEX = /^#([0-9a-f]{3}|[0-9a-f]{6})$/i;
+
+// A border container's sides, in the order `CT_PBdr` and `CT_TcBorders` both
+// declare them -- which is *not* the clockwise order the authoring surface
+// names them in. Each carries the declaration names it reads and the element
+// name it writes, built once: `borders` runs per paragraph and per cell, and
+// rebuilding four key strings per side per call is most of the garbage this
+// module makes.
+let SIDES = ["Top", "Left", "Bottom", "Right"].map((side) => ({
+  tag: side.toLowerCase(),
+  width: "border" + side + "Width",
+  line: "border" + side + "Style",
+  color: "border" + side + "Color",
+  pad: "padding" + side,
+}));
+
+/** @type {Record<string, string>} */
+let LINE = { solid: "single", dashed: "dashed", dotted: "dotted" };
+
+// The generic families as the names all three readers ship with; any other name
+// is written on the run for the reader to substitute, never embedded.
+/** @type {Record<string, string>} */
+let FAMILY = { sans: "Arial", serif: "Times New Roman", mono: "Courier New" };
+
+/** @type {Record<string, string>} */
+let JUSTIFY = { left: "left", center: "center", right: "right" };
+// Word's word for the middle is `center`; the authoring surface says `middle`.
+/** @type {Record<string, string>} */
+let VERTICAL = { top: "top", middle: "center", bottom: "bottom" };
+
+/** A declared colour as the six hex digits Word writes, or null.
+ *  @type {(value: any) => string | null} */
+// fallow-ignore-next-line code-duplication -- each target reads a declared hex into its own type; none may import a sibling, and the engine's stream is all they share
+let rgb = (value) => {
+  let match = typeof value === "string" && HEX.exec(value);
+  if (!match) return null;
+  // `#abc` is `#aabbcc`.
+  let digits = match[1].length === 3 ? match[1].replace(/./g, (d) => d + d) : match[1];
+  return digits.toUpperCase();
+};
+
+/** @type {(value: any) => number | null} */
+let points = (value) => (Number.isFinite(value) && value >= 0 ? value : null);
+/** A flag's on-element, its off-element, or nothing. Exact `true` and exact
+ *  `false` are declarations; anything else leaves the layer below in place.
+ *  @type {(value: any, tag: string) => string} */
+let flag = (value, tag) =>
+  value === true ? `<w:${tag}/>` : value === false ? `<w:${tag} w:val="0"/>` : "";
+
+/** @type {(value: any) => string} */
+let underline = (value) =>
+  value === true ? '<w:u w:val="single"/>' : value === false ? '<w:u w:val="none"/>' : "";
+
+/**
+ * The face a declared family names. A generic maps to the name all three
+ * readers ship with; any other is the author's own string, written for the
+ * reader to substitute and **escaped** — it is the one value in this module
+ * that is not a number, a hex colour or a closed name, so it is the one that
+ * reaches an attribute as the author wrote it (root CLAUDE.md, constraint 4).
+ *
+ * @type {(family: any) => string}
+ */
+let face = (family) => {
+  if (typeof family !== "string" || !family) return "";
+  let key = family.toLowerCase();
+  // Own-key lookup: `constructor` must not resolve an inherited member.
+  let name = esc(Object.hasOwn(FAMILY, key) ? FAMILY[key] : family);
+  return `<w:rFonts w:ascii="${name}" w:hAnsi="${name}" w:cs="${name}"/>`;
+};
+
+/** @type {(value: any) => string} */
+let halves = (value) => {
+  let size = points(value);
+  if (!size) return "";
+  // Half-points, and a size of zero is not a size.
+  let half = Math.round(size * 2);
+  return `<w:sz w:val="${half}"/><w:szCs w:val="${half}"/>`;
+};
+
+/** A container's own shading, from its `background`.
+ *  @type {(style: any) => string} */
+export let shading = (style) => shade(style?.background);
+
+/** @type {(value: any) => string} */
+let shade = (value) => {
+  let fill = rgb(value);
+  return fill ? `<w:shd w:val="clear" w:color="auto" w:fill="${fill}"/>` : "";
+};
+
+/** @type {(value: any) => string} */
+let tint = (value) => {
+  let color = rgb(value);
+  return color ? `<w:color w:val="${color}"/>` : "";
+};
+
+/**
+ * The run half of a resolved style, in `CT_RPr` order. Empty where the style
+ * declares nothing this target reads, so a run with no properties emits no
+ * `rPr` at all.
+ *
+ * `uppercase` is not here: Word's `caps` is a presentation the other two
+ * readers disagree about, so this target capitalises the string instead —
+ * Unicode default case mapping, never the host's locale, exactly as the PDF
+ * target does for its own reason (`text.js`).
+ *
+ * `boxed` is the same question `paraProps` asks below and means the same thing:
+ * *is this element the one that draws the box?* The box belongs to the
+ * innermost container that can hold one, so a `background` on a cell or an item
+ * is that container's shading and a run draws none — which is why the default
+ * here is `false` and there is `true`. Only a
+ * [styled run](../../../SCHEMA.md#cell-values) has nothing but the run to draw
+ * its own on.
+ *
+ * @type {(style: any, boxed?: boolean) => string}
+ */
+export let runProps = (style, boxed = false) =>
+  !style
+    ? ""
+    : face(style.family) +
+      flag(style.bold, "b") +
+      flag(style.italic, "i") +
+      flag(style.strikethrough, "strike") +
+      tint(style.color) +
+      halves(style.size) +
+      underline(style.underline) +
+      (boxed ? shade(style.background) : "");
+
+/** Whether a style asks for capitals. `false` is a declaration that turns an
+ *  outer layer's capitals off, which is the absence of the transform either way.
+ *  @type {(style: any) => boolean} */
+export let capitals = (style) => style?.uppercase === true;
+
+/** One border side, complete or nothing: a missing name never becomes a
+ *  reader's default black stroke.
+ *  @type {(style: any, side: (typeof SIDES)[number]) => string} */
+let edge = (style, side) => {
+  let width = points(style[side.width]);
+  let line = lineOf(style[side.line]);
+  let color = rgb(style[side.color]);
+  if (!width || !line || !color) return "";
+  // `w:sz` is eighths of a point, and Word clamps it to 2..96.
+  let eighths = Math.min(96, Math.max(2, Math.round(width * 8)));
+  return (
+    `<w:${side.tag} w:val="${line}" w:sz="${eighths}"` +
+    ` w:space="${spaceOf(style, side)}" w:color="${color}"/>`
+  );
+};
+
+/** @type {(named: any) => string | null} */
+let lineOf = (named) =>
+  typeof named === "string" && Object.hasOwn(LINE, named) ? LINE[named] : null;
+
+// A paragraph has no inset of its own, so an item's padding is approximated as
+// the space between its border and its text -- which is what the declaration
+// means on a surface that can draw it. Word writes that space in whole points,
+// 0 to 31, so a padding outside the range is clamped rather than dropped.
+/** @type {(style: any, side: (typeof SIDES)[number]) => number} */
+let spaceOf = (style, side) => Math.min(31, Math.round(points(style[side.pad]) || 0));
+
+/** @type {(style: any, wrap: string) => string} */
+export let borders = (style, wrap) => {
+  let out = "";
+  for (let side of SIDES) out += edge(style || {}, side);
+  return out && `<w:${wrap}>${out}</w:${wrap}>`;
+};
+
+/** @type {(value: any, tag: string, map: Record<string, string>) => string} */
+let named = (value, tag, map) =>
+  typeof value === "string" && Object.hasOwn(map, value) ? `<w:${tag} w:val="${map[value]}"/>` : "";
+
+/** @type {(style: any) => string} */
+let spacing = (style) => {
+  let attrs = gap("before", style.spaceBefore) + gap("after", style.spaceAfter);
+  return attrs && "<w:spacing" + attrs + "/>";
+};
+
+/** @type {(name: string, value: any) => string} */
+let gap = (name, value) => {
+  let own = points(value);
+  return own === null ? "" : ` w:${name}="${twips(own)}"`;
+};
+
+/**
+ * The paragraph half, in `CT_PPrBase` order.
+ *
+ * `boxed` is the same question `runProps` asks above. The box is drawn by the
+ * innermost container that can hold one: outside a table that is the paragraph,
+ * as borders and shading, with padding as the border space — the approximation
+ * `quario-vkgi.4` decided, because a paragraph has no inset. Inside a table cell
+ * it is the *cell*, which has one, so the paragraph there passes `boxed: false`
+ * or the reader draws two rules.
+ *
+ * @type {(style: any, boxed?: boolean) => string}
+ */
+export let paraProps = (style, boxed = true) =>
+  !style
+    ? ""
+    : (boxed ? borders(style, "pBdr") + shade(style.background) : "") +
+      spacing(style) +
+      named(style.align, "jc", JUSTIFY);
+
+/**
+ * The cell half, in `CT_TcPr` order, minus the width and span the table writer
+ * owns. A cell *does* have an inset, so padding is exact here rather than
+ * approximated, and the target's own padding fills the sides the author left
+ * unnamed — a named `0` beating it, which is what makes it a declaration
+ * (`docs/adr/0040`).
+ *
+ * @type {(style: any, pad: Record<string, number>) => string}
+ */
+export let cellProps = (style, pad) =>
+  borders(style || {}, "tcBorders") +
+  shade(style?.background) +
+  margins(style, pad) +
+  named(style?.valign, "vAlign", VERTICAL);
+
+// The cell inset a style that names none resolves to: the target's own padding,
+// which is one object for a whole render, so the element is built once per
+// padding rather than once per cell. A table of five thousand rows writes the
+// same twenty-odd bytes twenty-five thousand times otherwise.
+/** @type {Map<Record<string, number>, string>} */
+let PLAIN = new Map();
+
+/** @type {(style: any, pad: Record<string, number>) => string} */
+let margins = (style, pad) =>
+  SIDES.some((side) => points(style?.[side.pad]) !== null)
+    ? `<w:tcMar>${SIDES.map((side) => inset(side.tag, points(style?.[side.pad]) ?? pad[side.tag])).join("")}</w:tcMar>`
+    : plainMargins(pad);
+
+/** @type {(pad: Record<string, number>) => string} */
+let plainMargins = (pad) => {
+  let made = PLAIN.get(pad);
+  if (made) return made;
+  made = `<w:tcMar>${SIDES.map((side) => inset(side.tag, pad[side.tag])).join("")}</w:tcMar>`;
+  PLAIN.set(pad, made);
+  return made;
+};
+
+/** @type {(tag: string, value: number) => string} */
+let inset = (tag, value) => `<w:${tag} w:w="${twips(value)}" w:type="dxa"/>`;
+
+/**
+ * Style blocks layer outward-in: the enclosing block under the inner one. A
+ * `false` in the inner block is a declaration and wins, which a plain overwrite
+ * already gives — the engine has resolved everything else before the stream.
+ *
+ * @type {(under: any, over: any) => any}
+ */
+export let under = (outer, inner) =>
+  outer ? (inner ? { ...outer, ...inner } : outer) : inner || null;

package/lib/stylepart.js

@@ -0,0 +1,72 @@
+/**
+ * The `styles.xml` part, written on every render and carrying two things.
+ * Named for the part rather than for the vocabulary: `style.js` beside it is
+ * this target's reading of what an author declares, and the two are imported
+ * together often enough that one letter between them would be a trap.
+ *
+ * `docDefaults` is the base every run and paragraph inherits: the sans
+ * generic's own name, the report default's size, and the line spacing the
+ * other targets lay out at. It is the one place this target states a look
+ * through the style mechanism at all.
+ *
+ * The nine heading styles are what put a group in a reader's navigation pane,
+ * and each reader asks a different question of them. `<w:name w:val="heading
+ * 1"/>` is what binds Word's own built-in — the `styleId` is a local label and
+ * the name is the binding — `outlineLvl` is what the navigation pane reads,
+ * and Google Docs maps by `styleId`, which is why all three are written. The
+ * `qFormat` beside them is narrower than the other three: it puts the style in
+ * a reader's gallery, and is not what makes any of them recognise it.
+ *
+ * **`Normal` is deliberately empty.** The [report default](../../../SCHEMA.md)
+ * and every declaration an author writes are direct formatting on the runs and
+ * paragraphs that wear them, never folded in here: a look that depends on a
+ * style lookup is a look three readers may resolve three different ways, and
+ * this target's promise is the geometry and typography of the preview.
+ */
+import { W, XML } from "./xml.js";
+
+// The base. Arial is the name the sans generic maps to; 10 pt is `sz` in
+// half-points; 1.4 line spacing is `line` in 240ths of a line, `auto` so a
+// larger run still fits.
+const FAMILY = "Arial";
+const SIZE = 20;
+const LINE = 336;
+
+/** Word caps the outline at nine levels, and so does the deepest style here. */
+const LEVELS = 9;
+
+/** @type {(level: number) => string} */
+let heading = (level) =>
+  `<w:style w:type="paragraph" w:styleId="Heading${level}">` +
+  `<w:name w:val="heading ${level}"/>` +
+  '<w:basedOn w:val="Normal"/>' +
+  "<w:qFormat/>" +
+  `<w:pPr><w:outlineLvl w:val="${level - 1}"/></w:pPr>` +
+  "<w:rPr><w:b/></w:rPr>" +
+  "</w:style>";
+
+/** The part, identical on every render: nothing here reads the report. */
+export const STYLES =
+  XML +
+  `<w:styles ${W}>` +
+  "<w:docDefaults>" +
+  "<w:rPrDefault><w:rPr>" +
+  `<w:rFonts w:ascii="${FAMILY}" w:hAnsi="${FAMILY}" w:cs="${FAMILY}"/>` +
+  `<w:sz w:val="${SIZE}"/><w:szCs w:val="${SIZE}"/>` +
+  "</w:rPr></w:rPrDefault>" +
+  "<w:pPrDefault><w:pPr>" +
+  `<w:spacing w:line="${LINE}" w:lineRule="auto"/>` +
+  "</w:pPr></w:pPrDefault>" +
+  "</w:docDefaults>" +
+  '<w:style w:type="paragraph" w:default="1" w:styleId="Normal"><w:name w:val="Normal"/></w:style>' +
+  Array.from({ length: LEVELS }, (_, i) => heading(i + 1)).join("") +
+  "</w:styles>";
+
+/**
+ * The heading style a group header takes at this nesting depth, capped at the
+ * deepest one Word draws. Google Docs shows `Heading7` and deeper as body
+ * text — a documented best-effort edge, not something a level can fix.
+ *
+ * @type {(depth: number) => string}
+ */
+export let headingAt = (depth) => "Heading" + Math.min(depth + 1, LEVELS);

package/lib/table.js

@@ -0,0 +1,180 @@
+/**
+ * Real Word tables: the table detail, and the [split](../../../SCHEMA.md#split-item)
+ * bracket, which is the same thing with no rules and one row.
+ *
+ * A flow target measures nothing, so the grid is the only place a column width
+ * can be settled: declared shares are exact, in twips of the content width, and
+ * the columns that declared none divide what is left **evenly** rather than
+ * from their content. That is the one approximation `quario-vkgi.4`
+ * decided for this row, and it is why the layout is fixed — an automatic one would let the reader re-measure
+ * and lose the shares the author wrote.
+ *
+ * `CT_TblPrBase`, `CT_TrPr` and `CT_TcPr` are sequences like every other
+ * container this target writes; the order below is the contract.
+ */
+import { borders, cellProps, paraProps, shading, under } from "./style.js";
+import { looking, paragraph, runs } from "./text.js";
+
+/** The width of a table, as a fraction of the text column, in fiftieths of a
+ *  percent — which is how `pct` is spelled. */
+const FULL = '<w:tblW w:w="5000" w:type="pct"/>';
+
+// No rules: an unstyled table has the strokes the author declared and no
+// others, which is what the PDF and the worksheet already show. A reader's own
+// table default would be a look nothing in the report asked for.
+/** `CT_TblPrBase` order: the width, then the box, then the layout. */
+const LAYOUT = '<w:tblLayout w:type="fixed"/>';
+
+/**
+ * The grid, in twips. `shares` are the declared percentages, one per column,
+ * `null` where a column declared none; `width` is the content width in points.
+ * The engine has already refused a document whose fixed shares leave the
+ * width-less columns nothing, so the remainder here is never negative.
+ *
+ * @type {(shares: (number | null)[], width: number) => number[]}
+ */
+export let grid = (shares, width) => {
+  let total = Math.round(width * 20);
+  /** @type {(number | null)[]} */
+  let fixed = shares.map((share) =>
+    Number.isFinite(share) ? Math.round((/** @type {number} */ (share) / 100) * total) : null,
+  );
+  let spare = fixed.filter((w) => w === null).length;
+  let taken = 0;
+  for (let w of fixed) taken += w ?? 0;
+  let left = total - taken;
+  let each = spare ? Math.max(0, Math.round(left / spare)) : 0;
+  return fixed.map((w) => w ?? each);
+};
+
+/** @type {(widths: number[]) => string} */
+let tblGrid = (widths) =>
+  "<w:tblGrid>" + widths.map((w) => `<w:gridCol w:w="${w}"/>`).join("") + "</w:tblGrid>";
+
+/**
+ * One cell. `body` is the block content it holds — a cell must hold at least
+ * one paragraph, so an empty one still gets its own.
+ *
+ * @type {(cell: any, width: number, body: string, pad: Record<string, number>) => string}
+ */
+let tc = (cell, width, body, pad) =>
+  "<w:tc><w:tcPr>" +
+  `<w:tcW w:w="${width}" w:type="dxa"/>` +
+  (cell.span > 1 ? `<w:gridSpan w:val="${cell.span}"/>` : "") +
+  cellProps(cell.style, pad) +
+  "</w:tcPr>" +
+  (body || "<w:p/>") +
+  "</w:tc>";
+
+/**
+ * One row. `heading` repeats it after every page break, which is what keeps a
+ * long table readable and is the only thing `trPr` carries here.
+ *
+ * @type {(cells: string, heading?: boolean) => string}
+ */
+let tr = (cells, heading = false) =>
+  "<w:tr>" + (heading ? "<w:trPr><w:tblHeader/></w:trPr>" : "") + cells + "</w:tr>";
+
+/**
+ * A table. `style` is the box the table itself wears — a
+ * [split](../../../SCHEMA.md#split-item) keeps its own box, unlike a table row
+ * whose the engine has already resolved onto the cells, so this is where a
+ * split's borders and shading land.
+ *
+ * @type {(rows: string, widths: number[], style?: any) => string}
+ */
+export let tbl = (rows, widths, style = null) =>
+  "<w:tbl><w:tblPr>" +
+  FULL +
+  borders(style, "tblBorders") +
+  shading(style) +
+  LAYOUT +
+  "</w:tblPr>" +
+  tblGrid(widths) +
+  rows +
+  "</w:tbl>";
+
+// A split is a borderless table with no padding of its own: it places its slots
+// across the width and nothing more, which is what the other targets draw.
+const ZERO_PAD = { top: 0, left: 0, bottom: 0, right: 0 };
+
+/**
+ * A [split](../../../SCHEMA.md#split-item) being filled. Its slots arrive as
+ * separate events between the bracket, one per slot and in slot order, so the
+ * column a slot lands in is simply the next one.
+ *
+ * The split's own declarations are the layer under each slot's, and its box
+ * stays its own — unlike a table row's, which the engine has already resolved
+ * onto the cells before any target sees it (SCHEMA.md, "Splits").
+ *
+ * The body and a page band both fill one, and differ on nothing but what a
+ * picture inside a slot is capped at, which is why `content` takes the slot's
+ * own width.
+ *
+ * @type {(slots: any[], width: number, style: any) =>
+ *   { style: any, slot: (own: any, content: (column: number) => string) => void,
+ *     close: () => string }}
+ */
+export let splitting = (slots, width, style) => {
+  let widths = grid(
+    slots.map((/** @type {any} */ s) => (Number.isFinite(s.width) ? s.width : null)),
+    width,
+  );
+  let at = 0;
+  let cells = "";
+  return {
+    style,
+    slot: (own, content) => {
+      let column = widths[at++] || 0;
+      // `boxed: false`: the slot's box is the cell's, so the paragraph inside
+      // it must not draw a second one.
+      cells += tc(
+        { span: 1, style: own },
+        column,
+        paragraph(paraProps(own, false), content(column / 20)),
+        ZERO_PAD,
+      );
+    },
+    close: () => tbl(tr(cells), widths, style),
+  };
+};
+
+/**
+ * How wide one cell is, in twips: its own grid column, plus every column it
+ * [spans](../../../SCHEMA.md#span). `record` walks the cells in order and keeps
+ * the column it has reached, since a span consumes more than one.
+ *
+ * @type {(widths: number[], at: number, span: number) => number}
+ */
+let spanned = (widths, at, span) =>
+  widths.slice(at, at + Math.max(1, span || 1)).reduce((sum, w) => sum + w, 0);
+
+/**
+ * One row of cells, each wearing what the row layers over it and taking the
+ * grid columns it [spans](../../../SCHEMA.md#span). `heading` repeats the row
+ * after every page break.
+ *
+ * A table cell can no more hold a live field than a body paragraph can: only a
+ * page band binds the `page` anchor, which is why no sequence is named here.
+ *
+ * @type {(cells: any[], widths: number[], heading: boolean, layer: any,
+ *   how: { pad: Record<string, number>, intl: any }) => string}
+ */
+export let record = (cells, widths, heading, layer, how) => {
+  let at = 0;
+  let out = "";
+  for (let cell of cells) {
+    let style = under(layer, cell.style);
+    let span = Math.max(1, cell.span || 1);
+    out += tc(
+      { span: cell.span, style },
+      spanned(widths, at, span),
+      // `boxed: false`: the cell above draws the box, so the paragraph inside
+      // it must not draw a second one.
+      paragraph(paraProps(style, false), runs(cell.tokens, looking(style, how.intl))),
+      how.pad,
+    );
+    at += span;
+  }
+  return tr(out, heading);
+};

package/lib/text.js

@@ -0,0 +1,141 @@
+/**
+ * A cell's tokens as Word runs, and the paragraph that holds them. The one
+ * place this target turns the engine's token stream into markup, so the body
+ * and the page bands cannot drift on what a cell reads as.
+ *
+ * A token the engine tagged `page.number` or `page.total` (CONTEXT.md, "Live
+ * field") becomes a Word **field**, which the reader's application recomputes
+ * as the document repaginates. Anything computed from a page value is ordinary
+ * text, frozen at what the render saw.
+ *
+ * A cell's [styled runs](../../../SCHEMA.md#cell-values) are the engine's own
+ * grouping, taken through `styledRuns` so this target cannot drift from the
+ * others on what a run is. An authored newline is a hard break, which is a run
+ * of its own rather than a character, and `uppercase` capitalises the string
+ * here because Word's `caps` is a presentation the three readers disagree
+ * about — Unicode default case mapping, never the host's locale, so the bytes
+ * stay reproducible.
+ */
+import { display, format, styledRuns } from "quario";
+import { capitals, runProps } from "./style.js";
+import { esc } from "./xml.js";
+
+/** One paragraph, its properties already written.
+ *  @type {(props: string, inner: string) => string} */
+export let paragraph = (props, inner) =>
+  "<w:p>" + (props && "<w:pPr>" + props + "</w:pPr>") + inner + "</w:p>";
+
+// A hard break, and the newlines the engine's stream may carry (SCHEMA.md,
+// "Layout contract"): CRLF first, so a pair is one break and not two.
+const BREAK = "<w:br/>";
+let NEWLINE = /\r\n|\r|\n/;
+
+/** The one run element, with its properties and its text already settled.
+ *  @type {(text: string, look: string) => string} */
+let piece = (text, look) =>
+  "<w:r>" +
+  (look && "<w:rPr>" + look + "</w:rPr>") +
+  '<w:t xml:space="preserve">' +
+  esc(text) +
+  "</w:t></w:r>";
+
+/**
+ * One run's text, or nothing where there is none. An authored newline splits
+ * the run so a `<w:br/>` can sit between the halves — a break is an element in
+ * Word, not a character, so it cannot ride inside the `<w:t>`.
+ *
+ * @type {(text: string, look?: string) => string}
+ */
+export let run = (text, look = "") => {
+  if (!text) return "";
+  return text
+    .split(NEWLINE)
+    .map((line) => piece(line, look))
+    .join(BREAK);
+};
+
+/**
+ * One Word field, with no cached result. The result is deliberately absent:
+ * a cached one would be the page number the probe happened to read, which
+ * would make the two probe results differ for every band that numbers itself
+ * and so put a first-page part on every report. Word and the other readers
+ * compute `PAGE` and its two totals while laying the page out regardless.
+ *
+ * @type {(name: string) => string}
+ */
+let field = (name) =>
+  '<w:r><w:fldChar w:fldCharType="begin"/></w:r>' +
+  '<w:r><w:instrText xml:space="preserve"> ' +
+  name +
+  ' </w:instrText></w:r><w:r><w:fldChar w:fldCharType="end"/></w:r>';
+
+/** The field that gives a sequence's length: the document's, and a section's. */
+export const DOCUMENT_PAGES = "NUMPAGES";
+export const SECTION_PAGES = "SECTIONPAGES";
+
+/**
+ * A tagged token's field, or nothing where the token is ordinary text.
+ * `sequence` is the field that gives the current sequence's length —
+ * `NUMPAGES` for the document's, `SECTIONPAGES` inside a section a
+ * `reset: "page"` instance opened.
+ *
+ * @type {(token: any, sequence: string) => string}
+ */
+let fieldOf = (token, sequence) =>
+  token.field ? field(token.field === "page.number" ? "PAGE" : sequence) : "";
+
+/**
+ * One ordinary token's text: the cell's `format` declaration applied at the
+ * markup edge, falling back to the scalar display rule the whole stack shares,
+ * and capitalised where the style asks.
+ *
+ * @type {(token: any, look: Look) => string}
+ */
+let textOf = (token, look) => {
+  let text = "literal" in token ? token.literal : shown(token, look);
+  return look.caps ? text.toUpperCase() : text;
+};
+
+/** One interpolated value as text: the cell's `format` declaration at the
+ *  markup edge, falling back to the scalar rule the whole stack shares.
+ *  @type {(token: any, look: Look) => string} */
+let shown = (token, look) => format(token.value, look.style, look.intl) ?? display(token.value);
+
+/**
+ * What a stretch of text is written with: the resolved style it wears, the run
+ * properties that style became, whether it is capitalised, the instance's
+ * `format` configuration, and which field gives the current sequence's length.
+ * Carried together because every one of them is read for every token, and
+ * derived once per run rather than per token — `sequence` included, which is
+ * why nothing below it takes one as an argument.
+ *
+ * @typedef {{ style: any, props: string, caps: boolean, intl: any,
+ *   sequence: string }} Look
+ */
+
+/** @type {(style: any, intl: any, sequence?: string, boxed?: boolean) => Look} */
+export let looking = (style, intl, sequence = DOCUMENT_PAGES, boxed = false) => ({
+  style,
+  props: runProps(style, boxed),
+  caps: capitals(style),
+  intl,
+  sequence,
+});
+
+/**
+ * A cell's tokens as Word runs. The engine's `styledRuns` is the grouping, so
+ * a styled run's own resolved style replaces the cell's for its stretch — the
+ * two are already composed on the stream — and a tagged token stays a field
+ * whatever style it wears.
+ *
+ * @type {(tokens: any[], look: Look) => string}
+ */
+export let runs = (tokens, look) =>
+  styledRuns(tokens)
+    .map((styled) => {
+      let own = styled.style ? looking(styled.style, look.intl, look.sequence, true) : look;
+      return styled.tokens
+        .map((token) => fieldOf(token, own.sequence) || run(textOf(token, own), own.props))
+        .join("");
+    })
+    .join("");