@quario/docx 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,69 @@
 # @quario/docx
 
+## 0.2.0
+
+### Minor Changes
+
+- **A group's `break` names a position, and `break: "page"` is retired.** Its values are `"before"`, `"between"`, `"after"` and `"around"`. Write `break: "before"` where you wrote `break: "page"`. That is the whole of the migration, and it changes nothing the report produces.
+
+  The boundary between two consecutive instances always turns a page. `before` adds the leading edge of the run, so the first instance opens a page of its own. `between` adds neither edge, which keeps the first instance on the page the report header opened — the case the old vocabulary could not express, and the reason for the change. `after` adds the trailing edge, and `around` adds both. A trailing edge turns the page for what follows the run, so a report whose last band is that group reads `after` as `between` and `around` as `before`. A nested group takes its two edges from each instance of the group above it, rather than from the document. `"page"` said which unit a break used, where the four say where it falls; one set cannot say both and still read at a glance.
+
+  **`reset: "page"` turns no page of its own, and now needs a `break` beside it.** It says only that a new `page.number` / `page.total` sequence starts at this instance. A sequence owns whole pages, so `reset` requires `break` to be `"before"` or `"around"`. Any other `break`, and `reset` with no `break` at all, is a definition error the compile reports. Add `break: "before"` to a group that declares `reset` alone today.
+
+  The HTML target adds `q-break` to an instance whose leading edge turns, as before, and the new `q-break-after` to one whose trailing edge turns. `@quario/html/style.css` gains `.q-break-after { break-after: page }` beside the rule it already shipped for `.q-break`.
+
+  The Word target also stops losing a page break a table would swallow. A table carries no paragraph properties, so a break owed where one starts had nowhere to sit and reached the next paragraph instead, on the wrong page or on none. It now gets a paragraph of its own, the same carrier a section break already took.
+
+  The render-event stream states the two edges rather than the four positions. `group-start` carries `break` where a page turns before the instance, and the new `breakAfter` where one turns after it, so a target reads boundaries and never the position that asked for them.
+
+### Patch Changes
+
+- Updated dependencies
+  - quario@0.10.0
+
+## 0.1.1
+
+### Patch Changes
+
+- **Every target factory now refuses an option it does not understand.** An unknown key, a key with
+  a value of the wrong type, or an `options` that is not an object throws a `TypeError` at the
+  factory call, naming the option path — `options.meta.title`, `options.page.size`. `@quario/docx`
+  already behaved this way. `@quario/pdf`, `@quario/html`, `@quario/xlsx` and `@quario/layout` read
+  the keys they knew and ignored the rest, so a typo cost you the option you meant to set with no
+  signal at any point. `csv()` takes no options, and it refuses an argument rather than discarding
+  one.
+
+  The check itself is one thing, so the engine now exports it: `hostOptions` closes a key set and
+  `hostMeta` validates the `{ title, author, subject }` contract the document targets share. A
+  fourth document property is one edit rather than three.
+
+  **What this changes for you.** One options object spread across several targets stops working if
+  any target does not know one of its keys — `const o = { page, fonts, meta }` passed to `pdf(o)`,
+  `html(o)` and `xlsx(o)` is three different key sets. An object holding only what its consumers
+  share is unaffected, so `{ page, fonts }` into both `pdf()` and `layout()` still works.
+  TypeScript does not warn about this: excess-property checking fires on an object literal and not
+  on a variable, so a bag held in a `const` compiles clean and throws when you call the factory.
+
+  Nullish is absence everywhere, at both levels, so `{ meta: config.meta ?? null }` and
+  `{ meta: { title: config.title } }` over a config that carries neither are both fine.
+  `html({ paths })` now takes `true` or `false` rather than anything truthy, so `paths: "no"` throws
+  instead of turning path stamping on. A `fonts` mapping given as an array is refused by
+  `@quario/html` and `@quario/layout` rather than read as families named `0`, `1`, `2`.
+
+  Every host-option failure is now a `TypeError` rather than a plain `Error`. A `catch` that tests
+  `instanceof Error` is unaffected. One that compares the constructor is not.
+
+  `@quario/docx` is relaxed in three places, each of them now accepting what it refused: `meta: null`
+  and `page: null` are absence rather than errors, a property written as `meta: { title: undefined }`
+  is a property you did not write rather than one of the wrong type, and an inherited enumerable key
+  is no longer reported as an option you wrote.
+
+  `@quario/pdf`, `@quario/xlsx` and `@quario/docx` now copy `meta` at the factory call. Mutating the
+  object you passed no longer changes what a configured target writes.
+
+- Updated dependencies
+  - quario@0.9.0
+
 ## 0.1.0
 
 ### Minor Changes

package/README.md

@@ -11,7 +11,7 @@ npm install quario @quario/docx
 ```
 
 The engine is a peer dependency, installed beside the target. ESM-only, Node 22+, and
-browser-ready through any standards-based ESM bundler. The renderer resolves a `Uint8Array`; you
+browser-ready through any standards-based ESM bundler. The renderer resolves a `Uint8Array`. You
 write the file.
 
 ## Quick start
@@ -39,8 +39,8 @@ writeFileSync("orders.docx", bytes);
 
 ## Options
 
-Both are optional, and both are validated at the factory call — an unknown option, or one of the
-wrong type, throws there rather than at the first render.
+Both are optional. The factory call validates both: an unknown option, or one of the wrong type,
+throws there rather than at the first render.
 
 ```js
 docx({
@@ -56,27 +56,33 @@ docx({
 
 ## What it renders
 
-A report's bands become paragraphs; a table detail becomes a **real Word table** carrying the
+A report's bands become paragraphs. A table detail becomes a **real Word table** carrying the
 author's column shares as a fixed grid, with `span` as `gridSpan` and a header row that repeats
-after every page break. A split is a borderless one-row table, and an image is an inline picture at its natural size, capped at the text
-column, carrying its `alt` as the drawing's description.
+after every page break. A split is a borderless one-row table. An image is an inline picture at
+its natural size, capped at the text column, carrying its `alt` as the drawing's description.
 
 The grouping becomes the **navigation pane**: a group header's first item takes `Heading{depth+1}`
 from this package's own `styles.xml`, so no theme typography leaks in. Everything a report declares
-is direct formatting on the runs and paragraphs that wear it — `Normal` stays empty, because a look
+is direct formatting on the runs and paragraphs that wear it. `Normal` stays empty, because a look
 that depends on a style lookup is a look three readers may resolve three ways.
 
 Page bands become a section's header and footer. A bare `{{ page.number }}` or `{{ page.total }}`
-becomes a live `PAGE` / `NUMPAGES` field the reader's own application recomputes; anything computed
-from them is frozen at the value the render saw. A group's `reset: "page"` opens a section that
-restarts the numbering, and `break: "page"` starts the instance on a fresh page.
+becomes a live `PAGE` / `NUMPAGES` field the reader's own application recomputes. Anything computed
+from them freezes at the value the render saw. A group's `reset: "page"` opens a section that
+restarts the numbering, and a `break` turns a page at every boundary its position names.
 
 ## Determinism
 
-Two renders of one report are byte-identical, on **every supported runtime**: `fflate` is pure
-JavaScript, so its deflate output does not vary by engine. Every entry in the package is stamped
+Two renders of one report are byte-identical, on **every supported runtime**. `fflate` is pure
+JavaScript, so its deflate output does not vary by engine. The package stamps every entry
 1980-01-01 and nothing in the document carries a clock, so a digest over the bytes is a fair test.
 
+## Unlicensed marking
+
+An unlicensed render writes the wording from `report-start.marking` as the first paragraph of
+every footer. A licensed render writes none. The per-footer presence is normative. The wording's
+look is best-effort.
+
 ## Documentation
 
 [The quario documentation](https://getquario.com/docs/) is the reference.
@@ -87,14 +93,12 @@ of a declaration.
 
 ## License
 
-Commercial software with readable source. Free, unlimited, watermarked evaluation; per-developer
-licenses at [getquario.com](https://getquario.com). See the bundled LICENSE.
+Commercial software with readable source. Evaluation is free, unlimited, and watermarked.
+Per-developer licenses at [getquario.com](https://getquario.com). See the bundled LICENSE.
 
-Pass your license key once, on the instance; it is verified offline:
+Pass your license key once, on the instance. quario verifies it offline:
 
 ```js
 const q = quario({ license: "quario_..." });
 await q.license; // { licensed: true, licensee: "Acme BV", id: "1-ACME" }
 ```
-
-An unlicensed render carries the marking as the first paragraph of every footer.

package/lib/body.js

@@ -11,9 +11,13 @@
  * SCHEMA.md's "an instance already at the top of a page does not force an empty
  * page".
  *
- * **Page breaks.** `break: "page"` is `pageBreakBefore` on the instance's first
- * paragraph, skipped where the instance also declared `reset`, whose section has
- * already turned the page, and where it has nothing before it at all.
+ * **Page breaks.** The stream resolved a group's `break` position into the two
+ * edges of each instance (ADR 0077). A leading edge is `pageBreakBefore` on the
+ * instance's first paragraph, skipped where the instance also declared `reset`,
+ * whose section has already turned the page, and where it has nothing before it
+ * at all. A trailing edge is the same property on whatever paragraph follows the
+ * instance, and a document that ends owing one drops it: a break turns the page
+ * for what follows, and nothing follows.
  *
  * **Page columns.** A count on the report columns the body's own sections; a
  * count on a group wraps each instance in *continuous* section breaks, so the
@@ -28,19 +32,22 @@
  *
  * **Layers.** Outward-in: this target's baseline (`docDefaults`, so nothing is
  * written per run), the report default, the band-role default, then the node's
- * own — SCHEMA.md, "Style declarations". A `false` in an inner layer is a
- * declaration and wins, which a plain overwrite already gives.
+ * own. A `false` in an inner layer is a declaration and wins.
  */
 import { headingAt } from "./stylepart.js";
 import { paraProps, under } from "./style.js";
-import { grid, record, splitting, tbl } from "./table.js";
-import { describe, drawing, idOf, sizeOf } from "./picture.js";
+import { grid, record, tbl } from "./table.js";
+import { content, splitBlock } from "./content.js";
 import { EMPTY_CTX } from "./furniture.js";
-import { looking, paragraph, runs } from "./text.js";
+import { paragraph } from "./text.js";
+
+// The page break a paragraph wears, spelled once: `push` folds it into a
+// paragraph's own properties, and `carrier` gives it one where no paragraph is
+// coming to take it.
+const BREAK = "<w:pageBreakBefore/>";
 
 // The band roles this target supplies a default for, and the only look it puts
-// on a report that declared nothing. ADR 0014: a target supplies defaults where
-// its consumer has no seam to supply them, and a document is final on open.
+// on a report that declared nothing (ADR 0014: a document is final on open).
 // `test/omakase-defaults.test.js` holds this copy and the other two in
 // agreement; it is not shared code, and that is the ADR's point.
 /** @type {Record<string, any>} */
@@ -91,15 +98,12 @@ export let bodyOf = (section) => {
   /** What a render carries that the events do not: the report default, the
    *  instance's `format` configuration, the text column and the picture
    *  registry. Settled once, on the opening event, and read-only after —
-   *  `furniture.js`'s `Ctx`, so the two writers describe a render one way.
-   *  @type {import("./furniture.js").Ctx} */
+   *  `content.js`'s `Ctx`, so the two writers describe a render one way.
+   *  @type {import("./content.js").Ctx} */
   let ctx = EMPTY_CTX;
   /** The table being filled, if any: its grid, and the rows written so far. */
   /** @type {{ widths: number[], rows: string } | null} */
   let table = null;
-  /** The split being filled, if any. Splits never nest, so one is enough. */
-  /** @type {ReturnType<typeof splitting> | null} */
-  let split = null;
 
   // `CT_PPr` is a sequence and not a bag: `pStyle` is its first child,
   // `pageBreakBefore` its fourth, and everything `paraProps` writes comes after
@@ -107,17 +111,24 @@ export let bodyOf = (section) => {
   /** @type {(props: string, style: any, inner: string) => void} */
   let push = (props, style, inner) => {
     let look = owed.gapped ? under({ spaceBefore: GAP }, style) : style;
-    blocks.push({
-      props: props + (owed.broken ? "<w:pageBreakBefore/>" : "") + paraProps(look),
-      inner,
-    });
+    blocks.push({ props: props + (owed.broken ? BREAK : "") + paraProps(look), inner });
     owed = { broken: false, gapped: false };
   };
 
+  /** An empty paragraph, written where something is owed and no paragraph is
+   *  coming to take it: a section break whose last block is a table, and a page
+   *  break a table would otherwise swallow.
+   *  @type {(props?: string) => void} */
+  let carrier = (props = "") => void blocks.push({ props, inner: "" });
+
   /** A block that is not a paragraph -- a table -- which carries no properties
-   *  and so cannot take what the next paragraph is owed.
+   *  and so cannot take what the next paragraph is owed. A page break takes a
+   *  carrier of its own first, or the table would swallow it; the band gap
+   *  does not, because the next paragraph still takes it.
    *  @type {(inner: string) => void} */
   let block = (inner) => {
+    if (owed.broken) carrier(BREAK);
+    owed.broken = false;
     blocks.push({ props: "", inner, raw: true });
   };
 
@@ -128,15 +139,17 @@ export let bodyOf = (section) => {
     sections.push(section(kind));
   };
 
-  /** The report's own page-column count, and the depths of the instances that
-   *  opened a columned section, so `group-end` knows whose to close. */
+  /** The report's own page-column count. */
   let columns = 1;
-  /** @type {number[]} */
-  let columned = [];
+  /** One frame per open instance, innermost last: the columned section this
+   *  instance opened, if any, and its trailing page break. The brackets pair,
+   *  so `group-end` pops the frame `group-start` pushed.
+   *  @type {{ columns: number, trailing: boolean }[]} */
+  let instances = [];
   /** @type {(value: any) => number} */
   let counted = (value) => (Number.isInteger(value) && value > 1 ? value : 0);
 
-  /** @type {(own: import("./furniture.js").Ctx, event: any) => void} */
+  /** @type {(own: import("./content.js").Ctx, event: any) => void} */
   let start = (own, event) => {
     ctx = own;
     columns = counted(event.columns) || 1;
@@ -165,7 +178,7 @@ export let bodyOf = (section) => {
   let closeSection = () => {
     let last = blocks.at(-1);
     // oxlint-disable-next-line no-unused-expressions
-    (blocks.length === sectionStart || last?.raw) && blocks.push({ props: "", inner: "" });
+    (blocks.length === sectionStart || last?.raw) && carrier();
     /** @type {any} */ (blocks.at(-1)).closes = sections.at(-1);
   };
 
@@ -183,13 +196,12 @@ export let bodyOf = (section) => {
     // has not started: groups read as blocks without authored margins.
     // oxlint-disable-next-line no-unused-expressions
     owed.gapped ||= blocks.length > 0;
+    // Its own count is what `group-end` closes; a section that merely inherits
+    // the report's is not one this instance opened.
     let own = counted(event.columns);
+    instances.push({ columns: own, trailing: event.breakAfter === "page" });
     let kind = sectionFor(event.reset === "page", own);
     if (!kind) return breakBefore(event);
-    // Its own count is what `group-end` closes; a section that merely inherits
-    // the report's is not one this instance opened.
-    // oxlint-disable-next-line no-unused-expressions
-    own && columned.push(event.depth);
     reopen(kind);
   };
 
@@ -210,11 +222,19 @@ export let bodyOf = (section) => {
     open(kind);
   };
 
-  /** @type {(event: any) => void} */
-  let groupEnd = (event) => {
-    if (columned.at(-1) !== event.depth) return;
-    columned.pop();
-    reopen({ continuous: true, columns: columns });
+  /** What an instance's close owes, in the order the document takes them: the
+   *  trailing page break the stream stated when it opened, then the columned
+   *  section it opened.
+   *  @type {(frame: { columns: number, trailing: boolean }) => void} */
+  let closeInstance = (frame) => {
+    if (frame.trailing) owed.broken ||= blocks.length > 0;
+    if (frame.columns) reopen({ continuous: true, columns });
+  };
+
+  /** @type {() => void} */
+  let groupEnd = () => {
+    let frame = instances.pop();
+    if (frame) closeInstance(frame);
   };
 
   /**
@@ -230,20 +250,6 @@ export let bodyOf = (section) => {
     return owes;
   };
 
-  /** One item or picture, as the content of the paragraph it becomes. `column`
-   *  is what caps a picture: the text column, or the slot holding it.
-   *  @type {(event: any, style: any, column?: number) => string} */
-  let contentOf = (event, style, column = columnWidth()) =>
-    event.type === "image"
-      ? pictureRun(event, column)
-      : runs(event.tokens, looking(style, ctx.intl));
-
-  /** @type {(event: any, column: number) => string} */
-  let pictureRun = (event, column) => {
-    let rId = ctx.picture(event);
-    return drawing(event, idOf(rId), rId, describe(event), sizeOf(event, column));
-  };
-
   /** How wide the body is where it is being written: the text column, divided
    *  between the [page columns](../../../SCHEMA.md#page-columns) of the section
    *  it lands in, less the gutter between them. `708` twips is Word's own. */
@@ -254,23 +260,13 @@ export let bodyOf = (section) => {
 
   /** @type {(event: any) => void} */
   let itemOf = (event) => {
-    if (split) {
-      let own = under(split.style, event.style);
-      return split.slot(own, (column) => contentOf(event, own, column));
-    }
     let style = styleOf(event);
-    push(claimHeading(event.role), style, contentOf(event, style));
+    push(claimHeading(event.role), style, content(event, style, columnWidth(), ctx));
   };
 
   /** @type {(event: any) => void} */
-  let splitStart = (event) => {
-    split = splitting(event.slots, columnWidth(), styleOf(event));
-  };
-
-  let splitEnd = () => {
-    // oxlint-disable-next-line no-unused-expressions
-    split && block(split.close());
-    split = null;
+  let splitOf = (event) => {
+    block(splitBlock(event, columnWidth(), styleOf(event), ctx));
   };
 
   /** What a table's cells are written with. `intl` is settled on the opening
@@ -319,22 +315,27 @@ export let bodyOf = (section) => {
       "group-end": groupEnd,
       item: itemOf,
       image: itemOf,
-      "split-start": splitStart,
-      "split-end": splitEnd,
+      split: splitOf,
       "table-start": tableStart,
       row,
       "total-row": row,
       "table-end": tableEnd,
     },
     /** @type {(sectPr: (section: any) => string) => string} */
-    xml: (sectPr) =>
-      blocks
-        .map(
-          (b) =>
-            /** @type {any} */ (b).raw
-              ? b.inner
-              : paragraph(b.props + (b.closes ? sectPr(b.closes) : ""), b.inner),
-        )
-        .join("") + sectPr(sections.at(-1)),
+    xml: (sectPr) => {
+      // A page break the document ends owing is dropped, and `owed` is simply
+      // left set: a break turns the page for what follows it, and nothing
+      // follows. Word, the PDF and a printed fragment agree on that.
+      return (
+        blocks
+          .map(
+            (b) =>
+              /** @type {any} */ (b).raw
+                ? b.inner
+                : paragraph(b.props + (b.closes ? sectPr(b.closes) : ""), b.inner),
+          )
+          .join("") + sectPr(sections.at(-1))
+      );
+    },
   };
 };

package/lib/content.js

@@ -0,0 +1,50 @@
+/**
+ * What an item, a picture or a split becomes, one way for both writers: the
+ * body and a page band fill the same paragraphs and the same one-row table,
+ * and differ on nothing but the layer under an event's style and which field
+ * numbers the pages. Both arrive in `ctx`, so neither writer keeps a copy.
+ */
+import { describe, drawing, idOf, sizeOf } from "./picture.js";
+import { under } from "./style.js";
+import { splitting } from "./table.js";
+import { looking, runs } from "./text.js";
+
+/**
+ * What a render carries that the events do not: the report default every band
+ * item wears under its own, the instance's `format` configuration, the text
+ * column a picture is capped at, the registry a picture's bytes become a part
+ * in, and -- for a page band only -- which field gives the length of the
+ * sequence its section numbers. Both writers hand one of these down, so they
+ * describe a render one way.
+ *
+ * @typedef {{ base: any, intl: any, width: number,
+ *   picture: (event: any) => string, sequence?: string }} Ctx
+ */
+
+/**
+ * One item's or picture's content: the runs a text item's tokens become, or
+ * the inline drawing a picture is. `column` is what caps a picture: the text
+ * column, or the slot holding it.
+ *
+ * @type {(event: any, style: any, column: number, ctx: Ctx) => string}
+ */
+export let content = (event, style, column, ctx) => {
+  if (event.type !== "image") return runs(event.tokens, looking(style, ctx.intl, ctx.sequence));
+  let rId = ctx.picture(event);
+  return drawing(event, idOf(rId), rId, describe(event), sizeOf(event, column));
+};
+
+/**
+ * One split, folded, as the borderless one-row table it becomes: a slot per
+ * cell, each slot's own style layered over the split's, which is `style`.
+ *
+ * @type {(event: any, width: number, style: any, ctx: Ctx) => string}
+ */
+export let splitBlock = (event, width, style, ctx) => {
+  let split = splitting(event.slots, width, style);
+  for (let slot of event.items) {
+    let own = under(split.style, slot.style);
+    split.slot(own, (column) => content(slot, own, column, ctx));
+  }
+  return split.close();
+};

package/lib/furniture.js

@@ -14,16 +14,15 @@
  * what the probe below saw.
  *
  * *Where* on the page comes from the **probe**: the band closure is evaluated
- * at page 1 of 2 and at page 2 of 2, and the two results are compared. Equal —
- * which is what a band holding nothing but fields and literal text is — means
- * one part and no `titlePg`; different means a first-page part, a default one,
- * and `titlePg` in the section. The probe assumes a total of two, so a band
- * gated on `page.total` sees 2, exactly as the PDF target's height probe does.
+ * at page 1 of 2 and at page 2 of 2, and the two results are compared. Equal
+ * means one part and no `titlePg`; different means a first-page part, a
+ * default one, and `titlePg` in the section. The probe assumes a total of two,
+ * so a band gated on `page.total` sees 2.
  */
-import { describe, drawing, idOf, sizeOf } from "./picture.js";
+import { splits } from "quario";
+import { content, splitBlock } from "./content.js";
 import { paraProps, under } from "./style.js";
-import { splitting } from "./table.js";
-import { looking, paragraph, run, runs } from "./text.js";
+import { paragraph, run } from "./text.js";
 import { R, W, XML } from "./xml.js";
 
 // The two pages every band is read at, in order: the first of two, then a
@@ -40,67 +39,32 @@ const MARKING_LOOK = '<w:color w:val="808080"/><w:sz w:val="14"/>';
 
 /**
  * One band's events as the blocks they become: an item or a picture is a
- * paragraph, a split is a borderless one-row table, and the bracket is filled
- * exactly as the body fills one — `splitting` is the shared rule, so the two
- * cannot drift on what a split is.
- *
- * `ctx` is what a render carries that the events do not: the report default
- * every band item wears under its own, the instance's `format` configuration,
- * the text column a picture is capped at, and the registry a picture's bytes
- * become a part in.
+ * paragraph, a split is a borderless one-row table. `splitting` is the shared
+ * rule, so this and the body cannot drift on what a split is.
  *
  * @type {(events: any[], ctx: Band) => string}
  */
 let banded = (events, ctx) => {
-  /** @type {{ out: string, split: ReturnType<typeof splitting> | null }} */
-  let state = { out: "", split: null };
-  for (let e of events) STEPS.get(e.type)?.(state, e, ctx);
-  return state.out;
-};
-
-/** @type {(state: any, e: any, ctx: Band) => void} */
-let open = (state, e, ctx) => {
-  state.split = splitting(e.slots, ctx.width, under(ctx.base, e.style));
+  let out = "";
+  for (let e of splits(events)) out += STEPS[e.type]?.(e, ctx) ?? "";
+  return out;
 };
 
-/** @type {(state: any) => void} */
-let close = (state) => {
-  state.out += state.split ? state.split.close() : "";
-  state.split = null;
-};
-
-/** One item or picture, into the split being filled or into the band itself.
- *  @type {(state: any, e: any, ctx: Band) => void} */
-let draw = (state, e, ctx) => {
-  if (state.split) {
-    let own = under(state.split.style, e.style);
-    return state.split.slot(own, (/** @type {number} */ column) => content(e, own, column, ctx));
-  }
+/** One item or picture, as the paragraph it becomes in the band.
+ *  @type {(e: any, ctx: Band) => string} */
+let draw = (e, ctx) => {
   let style = under(ctx.base, e.style);
-  state.out += paragraph(paraProps(style), content(e, style, ctx.width, ctx));
+  return paragraph(paraProps(style), content(e, style, ctx.width, ctx));
 };
 
-// What each kind of band event does to the band being built. An event this does
-// not know contributes nothing rather than failing, which is what lets a
-// consumer written before an event kind existed go on working.
-/** @type {Map<string, (state: any, e: any, ctx: Band) => void>} */
-const STEPS = new Map([
-  ["split-start", open],
-  ["split-end", close],
-  ["item", draw],
-  ["image", draw],
-]);
+/** @type {(e: any, ctx: Band) => string} */
+let drawSplit = (e, ctx) => splitBlock(e, ctx.width, under(ctx.base, e.style), ctx);
 
-/**
- * One item's or picture's content.
- *
- * @type {(e: any, style: any, column: number, ctx: Band) => string}
- */
-let content = (e, style, column, ctx) => {
-  if (e.type !== "image") return runs(e.tokens, looking(style, ctx.intl, ctx.sequence));
-  let rId = ctx.picture(e);
-  return drawing(e, idOf(rId), rId, describe(e), sizeOf(e, column));
-};
+// What each kind of band event becomes. An event this does not know
+// contributes nothing rather than failing, which is what lets a consumer
+// written before an event kind existed go on working.
+/** @type {Record<string, (e: any, ctx: Band) => string>} */
+const STEPS = { split: drawSplit, item: draw, image: draw };
 
 /**
  * One reading of a band at one page, behind whatever the target leads the part
@@ -110,16 +74,7 @@ let content = (e, style, column, ctx) => {
  */
 let reading = (closure, at, lead, ctx) => lead + (closure ? banded(closure(at), ctx) : "");
 
-/**
- * What a render carries that the events do not: the report default every band
- * item wears under its own, the instance's `format` configuration, the text
- * column a picture is capped at, and the registry a picture's bytes become a
- * part in. `body.js` holds the same shape, so the two writers describe a render
- * one way.
- *
- * @typedef {{ base: any, intl: any, width: number,
- *   picture: (event: any) => string }} Ctx
- */
+/** @typedef {import('./content.js').Ctx} Ctx */
 
 /**
  * A `Ctx` for one sequence: the same render, plus which field gives the length
@@ -130,9 +85,9 @@ let reading = (closure, at, lead, ctx) => lead + (closure ? banded(closure(at),
  */
 
 /**
- * The part registry: every distinct part written once, whatever asks for it.
- * Sections opened by `reset: "page"` all number themselves the same way, so a
- * document of two hundred invoices carries one footer part, not two hundred.
+ * The part registry: every distinct part written once. Sections opened by
+ * `reset: "page"` all number themselves the same way, so a document of two
+ * hundred invoices carries one footer part.
  *
  * @param {any} [page] `report-start.page`, absent when no band is declared.
  * @param {string} [marking] The wording, on an unlicensed render.
@@ -167,8 +122,7 @@ export let furnish = (page, marking, relate = () => "", ctx = EMPTY_CTX) => {
   // reads it as "the first page takes the first-page parts" -- so a band with
   // no `first` reference shows *nothing* on page one once the other band has
   // turned it on. Both therefore name a first-page part whenever either needs
-  // one; the steady one names the part it already wrote, which the registry
-  // hands back rather than writing twice.
+  // one; the steady one names the part it already wrote.
   /** @type {(kind: string, pair: string[], titlePg: boolean) => string} */
   let references = (kind, [first, later], titlePg) => {
     /** @type {(type: string, body: string) => string} */

package/lib/index.d.ts

@@ -18,7 +18,11 @@ export interface DocxMeta {
   subject?: string;
 }
 
-/** Host controls, taken and validated at the factory call. */
+/**
+ * Host controls, taken and validated at the factory call: an option this
+ * target does not understand, or one of the wrong type, throws a `TypeError`
+ * there rather than costing the host the option in silence.
+ */
 export interface DocxOptions {
   page?: DocxPage;
   meta?: DocxMeta;

package/lib/index.js

@@ -6,12 +6,10 @@
  * one is quario's.
  *
  * This module is the entry — the options a host writes, the walk over the
- * stream, and the parts a package is made of. The writers each event kind
- * needs live beside it: `body.js` for the paragraphs a report resolves to,
- * `furniture.js` for the parts a page band becomes, `styles.js` for the base
- * every part inherits, and `text.js` for the runs all of them are made of.
+ * stream, and the parts a package is made of. The writers live beside it:
+ * `body.js`, `furniture.js`, `styles.js` and `text.js`.
  */
-import { walk } from "quario";
+import { hostMeta, hostOptions, splits, walk } from "quario";
 import { bodyOf } from "./body.js";
 import { DOCUMENT_NS, furnish } from "./furniture.js";
 import { STYLES } from "./stylepart.js";
@@ -29,44 +27,6 @@ const WML = "application/vnd.openxmlformats-officedocument.wordprocessingml";
 // own default, and what the page bands will be laid against.
 const FURNITURE = 720;
 
-/** @type {(msg: string) => never} */
-let err = (msg) => {
-  throw Error(msg);
-};
-
-// Split from `object` below rather than inlined: the three terms together
-// breach the complexity budget `npm run fallow` holds this package to.
-/** @type {(value: any) => boolean} */
-let plain = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
-
-/** @type {(value: any, at: string) => any} */
-let object = (value, at) => {
-  // oxlint-disable-next-line no-unused-expressions
-  value === undefined || plain(value) || err(at + ": expected an object");
-  return value;
-};
-
-/** @type {(value: any, keys: string[], at: string) => void} */
-let only = (value, keys, at) => {
-  for (let key in value) if (!keys.includes(key)) err(at + ': unknown option "' + key + '"');
-};
-
-// The three document properties a host may write.
-let PROPERTIES = ["title", "author", "subject"];
-
-// The document properties, validated: strings, and never a date. What a host
-// cannot write is what keeps a render deterministic -- `core.xml` is the one
-// part with a slot for a clock, and it has none of them.
-/** @type {(meta: any) => any} */
-let metaOf = (meta) => {
-  object(meta, "options.meta");
-  only(meta, PROPERTIES, "options.meta");
-  for (let key in meta)
-    // oxlint-disable-next-line no-unused-expressions
-    typeof meta[key] === "string" || err("options.meta." + key + ": expected a string");
-  return meta;
-};
-
 /**
  * One section. The child order is the schema's and Word is strict about it:
  * the part references, then `type`, the geometry, `pgNumType`, `cols`, and
@@ -191,15 +151,18 @@ let parts = (body, meta, furniture, rels) => ({
  * bytes described in SCHEMA.md ("The DOCX target"). Options are taken and
  * validated at the factory call.
  *
- * @param {any} [options] Host controls: `page` and `meta`.
+ * @import { DocxOptions } from './index.d.ts'
+ *
+ * @param {DocxOptions} [options] Host controls (see SCHEMA.md, "The DOCX target").
  * @returns {{name: "docx", compile: (stream: any) => (data?: any) => Promise<Uint8Array>}}
  *   The target (see SCHEMA.md, "Instances and targets").
  */
 export function docx(options) {
-  object(options, "options");
-  only(options, ["page", "meta"], "options");
-  let page = object(options?.page, "options.page");
-  let meta = metaOf(options?.meta);
+  hostOptions(options, ["page", "meta"], "options");
+  // Closed here rather than in `pageBox`, for the reason the layout package
+  // gives at the same call: the surface elements share that function.
+  let page = hostOptions(options?.page, ["size", "margin"], "options.page");
+  let meta = hostMeta(options?.meta, "options.meta");
   // The size fails here rather than at the first render: a host wrote it, so
   // a host hears about it where it was written. The margin is validated again
   // per render, because the document may be the one declaring it.
@@ -209,9 +172,7 @@ export function docx(options) {
     // The sections are written after the walk, so the opening event is taken
     // in its handler rather than peeked ahead of the driver: the margin a
     // document may declare instead of the host is settled by the time any
-    // second event is pulled, and the stream reaches `walk` unwrapped. The
-    // walk is what spends the render's budget and breathes for the host
-    // meanwhile.
+    // second event is pulled, and the stream reaches `walk` unwrapped.
     let geo = geometry(page);
     // Every relationship the document carries, in one place: the parts it
     // always has, then whatever the furniture and the body ask for. One
@@ -227,13 +188,11 @@ export function docx(options) {
       rels.push({ path: "word/" + target, target, kind, rId });
       return rId;
     };
-    // One part per distinct picture. Keyed on the bytes themselves: the
+    // One part per distinct picture, keyed on the bytes themselves: the
     // page-band probe reads each band twice and every section reads it again,
-    // and a logo that arrived by reading a field is the same array each time,
-    // so the part -- and the header XML naming it -- stays identical and the
-    // furniture's own dedup still collapses the sections. A `source` that
-    // *computes* fresh bytes per call writes a part per call, which is
-    // wasteful and still correct.
+    // so the part stays identical and the furniture's dedup still collapses
+    // the sections. A `source` computing fresh bytes per call writes a part
+    // per call, which is wasteful and still correct.
     /** @type {Map<Uint8Array, string>} */
     let drawn = new Map();
     /** @type {(event: any) => string} */
@@ -254,13 +213,13 @@ export function docx(options) {
       ...furniture.refsFor(kind.reset ? SECTION_PAGES : DOCUMENT_PAGES),
     });
     let body = bodyOf(section);
-    await walk(stream(data), {
+    await walk(splits(stream(data)), {
       ...body.handlers,
       "report-start": (event) => {
         geo = geometry(page, event);
         // What a render carries that the events do not, settled once and handed
         // to both writers: a fifth instance field must be read here and nowhere
-        // else (`furniture.js`, `Ctx`).
+        // else (`content.js`, `Ctx`).
         let ctx = {
           base: event.style || null,
           intl: { locale: event.locale, currency: event.currency, timeZone: event.timeZone },

package/lib/pack.js

@@ -3,11 +3,8 @@
  * fflate, which is what makes the writer a seam — a later one (a sibling OOXML
  * writer, `CompressionStream`) replaces this file and nothing else.
  *
- * Only the synchronous names are ever called. The asynchronous family would
- * reach for a worker built from a string, and the suites run under
- * `--disallow-code-generation-from-strings` with the browser page under a
- * `default-src 'none'` policy, so the path this target takes is proved rather
- * than promised.
+ * Only the synchronous names are ever called: the asynchronous family would
+ * reach for a worker built from a string.
  */
 import { strToU8, zipSync } from "fflate";
 

package/lib/page.js

@@ -5,14 +5,11 @@
  * — the rules and their wording, not the frame derivation this target has no
  * use for, because Word does the paginating.
  *
- * ADR 0039 gates the page-size table to one home, and `test/page-sizes.test.js`
- * is that gate: a second table is a size that means one thing here and another
- * there. This target is the one consumer that cannot reach the layout's — a
- * flow target measures nothing, and taking `@quario/layout` would install the
- * pagination engine and its font metrics for a two-entry table (ADR 0014: a
- * target imports only public engine helpers). So the copy is hand-synced under
- * that same gate, which asserts this table and these wordings against the
- * layout's: change one and change the other, or the gate fails.
+ * This target cannot reach the layout's: taking `@quario/layout` would install
+ * the pagination engine and its font metrics for a two-entry table (ADR 0014).
+ * So the copy is hand-synced under `test/page-sizes.test.js`, which asserts
+ * this table and these wordings against the layout's: change one and change
+ * the other, or the gate fails (ADR 0039).
  */
 
 // The named sizes, in points, exactly as `@quario/layout` states them; the
@@ -25,7 +22,7 @@ let SIZES = /** @type {Record<string, [number, number]>} */ ({
 
 /** @type {(msg: string) => never} */
 let err = (msg) => {
-  throw Error(msg);
+  throw TypeError(msg);
 };
 
 /** @type {(value: number) => boolean} */

package/lib/picture.js

@@ -71,8 +71,7 @@ export let drawing = (event, id, rId, alt, size) => {
 };
 
 /**
- * A picture's description, joined through the engine's own display rule — so a
- * `Date` in an `alt` reads as ISO 8601 UTC here as it does everywhere else, and
+ * A picture's description, joined through the engine's own display rule, so
  * the bytes do not move with the host's zone.
  *
  * @type {(event: any) => string}
@@ -81,10 +80,9 @@ export let describe = (event) => text(event.alt || []);
 
 /**
  * The number that names a drawing: its relationship's. One id space for the
- * whole document, which is what `docPr` wants — a counter per writer hands the
- * same number to a page band's picture and the body's — and stable across the
- * two readings of a band, where a running count would move and make every band
- * holding a logo look like one that differs on the first page.
+ * whole document, which is what `docPr` wants, and stable across the two
+ * readings of a band — a running count would move and make every band holding
+ * a logo look like one that differs on the first page.
  *
  * @type {(rId: string) => number}
  */

package/lib/style.js

@@ -1,9 +1,7 @@
 /**
- * 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.
+ * This target's reading of the closed style vocabulary. 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,
@@ -22,10 +20,9 @@ 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.
+// names them in. Built once: `borders` runs per paragraph and per cell, and
+// rebuilding four key strings per side per call is most of this module's
+// garbage.
 let SIDES = ["Top", "Left", "Bottom", "Right"].map((side) => ({
   tag: side.toLowerCase(),
   width: "border" + side + "Width",
@@ -74,9 +71,8 @@ let underline = (value) =>
 /**
  * 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).
+ * reader to substitute and **escaped** — the one value in this module that is
+ * not a number, a hex colour or a closed name.
  *
  * @type {(family: any) => string}
  */
@@ -123,13 +119,10 @@ let tint = (value) => {
  * 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.
+ * `boxed` is the same question `paraProps` asks below: *is this element the
+ * one that draws the box?* The box belongs to the innermost container that can
+ * hold one, which is why the default here is `false` and there `true`. Only a
+ * [styled run](../../../SCHEMA.md#cell-values) has nothing but the run.
  *
  * @type {(style: any, boxed?: boolean) => string}
  */

package/lib/stylepart.js

@@ -1,8 +1,7 @@
 /**
  * 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.
+ * Named for the part rather than the vocabulary: `style.js` beside it is this
+ * target's reading of what an author declares.
  *
  * `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

package/package.json

@@ -1,7 +1,14 @@
 {
   "name": "@quario/docx",
-  "version": "0.1.0",
-  "description": "The Word render target for quario — a flow target: real Word tables, a navigable outline, live page-number fields",
+  "version": "0.2.0",
+  "description": "Tiny, flow-based Word render target for quario. Real Word tables, a navigable outline, live page-number fields.",
+  "keywords": [
+    "csp",
+    "docx",
+    "ooxml",
+    "quario",
+    "word"
+  ],
   "homepage": "https://getquario.com",
   "license": "SEE LICENSE IN LICENSE",
   "repository": {
@@ -41,12 +48,12 @@
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.18.3",
     "@size-limit/preset-small-lib": "^13.0.3",
-    "quario": "^0.8.0",
+    "quario": "^0.10.0",
     "size-limit": "^13.0.3",
     "typescript": "^7.0.2"
   },
   "peerDependencies": {
-    "quario": "^0.8.0"
+    "quario": "^0.10.0"
   },
   "size-limit": [
     {