@quario/docx 0.1.1 → 0.3.0

package/lib/furniture.js

@@ -14,16 +14,16 @@
  * 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 { relationships } from "./rels.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 +40,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));
-};
-
-/** @type {(state: any) => void} */
-let close = (state) => {
-  state.out += state.split ? state.split.close() : "";
-  state.split = null;
+  let out = "";
+  for (let e of splits(events)) out += STEPS[e.type](e, ctx);
+  return out;
 };
 
-/** 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 +75,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,18 +86,24 @@ 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.
- * @param {(kind: string, target: string) => string} [relate] Registers a part
- *   and returns the relationship that reaches it; the caller owns the document's
- *   one allocator, because the body draws pictures too.
- * @param {Ctx} [ctx] What a render carries that the events do not.
+ * A band's own picture or link is a relationship of *its* part rather than of
+ * `document.xml`, so each reading records what it allocated and the part is
+ * written beside its own `.rels`. A reader that cannot resolve an `r:id` in the
+ * part it reads it from has a broken reference, however well the document
+ * resolves the same id.
+ *
+ * @param {any} page `report-start.page`, absent when no band is declared.
+ * @param {string} marking The wording, on an unlicensed render.
+ * @param {{ rels: any[], relate: (kind: string, target: string) => string }}
+ *   registry The document's one relationship registry; the caller owns it,
+ *   because the body draws pictures and links too.
+ * @param {Ctx} ctx What a render carries that the events do not.
  */
-export let furnish = (page, marking, relate = () => "", ctx = EMPTY_CTX) => {
+export let furnish = (page, marking, registry, ctx) => {
   /** @type {Record<string, string>} */
   let parts = {};
   /** @type {Map<string, string>} */
@@ -149,17 +111,34 @@ export let furnish = (page, marking, relate = () => "", ctx = EMPTY_CTX) => {
   /** @type {Record<string, number>} */
   let counts = { header: 0, footer: 0 };
 
-  // A part for this body, or the one already written for it.
-  /** @type {(kind: string, body: string) => string} */
-  let partFor = (kind, body) => {
+  // What the reading being taken has allocated: replaced per reading, and
+  // closed over by the wrappers below, so each part learns its own.
+  /** @type {Set<string>} */
+  let used = new Set();
+  /** @type {(allocate: any) => any} */
+  let recording = (allocate) => (/** @type {any} */ of) => {
+    let rId = allocate(of);
+    used.add(rId);
+    return rId;
+  };
+
+  // A part for this body, or the one already written for it. Identical markup
+  // refers to identical ids -- a picture is one part however often it is drawn
+  // -- so a part found by its markup is found with its relationships too.
+  /** @type {(kind: string, reading: { xml: string, used: Set<string> }) => string} */
+  let partFor = (kind, reading) => {
     let tag = kind === "header" ? "hdr" : "ftr";
-    let xml = XML + `<w:${tag} ${W}>` + body + `</w:${tag}>`;
+    let xml = XML + `<w:${tag} ${W}>` + reading.xml + `</w:${tag}>`;
     let seen = byXml.get(xml);
     if (seen) return seen;
     let target = kind + ++counts[kind] + ".xml";
-    let rId = relate(kind, target);
+    let rId = registry.relate(kind, target);
     byXml.set(xml, rId);
     parts["word/" + target] = xml;
+    if (reading.used.size)
+      parts["word/_rels/" + target + ".rels"] = relationships(
+        registry.rels.filter((rel) => reading.used.has(rel.rId)),
+      );
     return rId;
   };
 
@@ -167,13 +146,12 @@ 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.
-  /** @type {(kind: string, pair: string[], titlePg: boolean) => string} */
+  // one; the steady one names the part it already wrote.
+  /** @type {(kind: string, pair: any[], titlePg: boolean) => string} */
   let references = (kind, [first, later], titlePg) => {
-    /** @type {(type: string, body: string) => string} */
-    let ref = (type, body) =>
-      `<w:${kind}Reference w:type="${type}" r:id="${partFor(kind, body)}"/>`;
+    /** @type {(type: string, reading: any) => string} */
+    let ref = (type, reading) =>
+      `<w:${kind}Reference w:type="${type}" r:id="${partFor(kind, reading)}"/>`;
     return (titlePg ? ref("first", first) : "") + ref("default", later);
   };
 
@@ -186,7 +164,12 @@ export let furnish = (page, marking, relate = () => "", ctx = EMPTY_CTX) => {
    * @type {(sequence: string) => { refs: string, titlePg: boolean }}
    */
   let refsFor = (sequence) => {
-    let band = { ...ctx, sequence };
+    let band = {
+      ...ctx,
+      sequence,
+      picture: recording(ctx.picture),
+      link: recording(ctx.link),
+    };
     let lead = marking ? paragraph("", run(marking, MARKING_LOOK)) : "";
     let bands = [
       { kind: "header", closure: page?.header, lead: "" },
@@ -195,9 +178,12 @@ export let furnish = (page, marking, relate = () => "", ctx = EMPTY_CTX) => {
       .filter((band) => band.closure || band.lead)
       .map(({ kind, closure, lead: own }) => ({
         kind,
-        pair: PROBE.map((at) => reading(closure, at, own, band)),
+        pair: PROBE.map((at) => {
+          used = new Set();
+          return { xml: reading(closure, at, own, band), used };
+        }),
       }));
-    let titlePg = bands.some(({ pair }) => pair[0] !== pair[1]);
+    let titlePg = bands.some(({ pair }) => pair[0].xml !== pair[1].xml);
     return {
       refs: bands.map(({ kind, pair }) => references(kind, pair, titlePg)).join(""),
       titlePg,
@@ -207,8 +193,14 @@ export let furnish = (page, marking, relate = () => "", ctx = EMPTY_CTX) => {
   return { parts, refsFor };
 };
 
-/** A render that declares no bands and marks nothing needs none of it. */
-export const EMPTY_CTX = { base: null, intl: null, width: 0, picture: () => "" };
+/** A document nothing has furnished yet: the value a render carries until its
+ *  opening event says what its page bands are. A stream walked from part-way
+ *  through never replaces it, and still describes a page. */
+/** @type {{ parts: Record<string, string>, refsFor: (sequence: string) => { refs: string, titlePg: boolean } }} */
+export const NO_FURNITURE = {
+  parts: {},
+  refsFor: () => ({ refs: "", titlePg: false }),
+};
 
 /** The namespaces a document referencing furniture declares. */
 export const DOCUMENT_NS = W + " " + R;

package/lib/index.d.ts

@@ -34,3 +34,27 @@ export interface DocxOptions {
  * bytes described in SCHEMA.md ("The DOCX target").
  */
 export function docx(options?: DocxOptions): Target<"docx", Promise<Uint8Array>>;
+
+/** What a target makes of a declaration: CONTEXT.md's fate vocabulary. */
+export type Fate = "resolved" | "approximated" | "withdrawn" | "unread";
+
+/**
+ * What this target makes of each declaration SCHEMA.md's support matrix
+ * names. Hand-written and gated against that matrix rather than generated
+ * from it. It carries no version of its own: the package that ships it is the
+ * version.
+ *
+ * Keyed by the schema name an author writes — `valign`, `break`, `page.margin`
+ * — so a host, a `required` marking and a problem message share one
+ * vocabulary. Two matrix rows share the bare word `width`, so each is
+ * qualified by what carries it: `column.width` and `slot.width`.
+ *
+ * It covers the declarations every official target states one fate for. An
+ * absent key means the matrix states no single fate for that row — a row that
+ * summarises more than one declaration, or that describes a behaviour — never
+ * that this target has no answer.
+ */
+export const capabilities: {
+  readonly target: "docx";
+  readonly declarations: Readonly<Record<string, Fate>>;
+};

package/lib/index.js

@@ -6,23 +6,19 @@
  * 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 { hostMeta, hostOptions, walk } from "quario";
+import { collapse, hostMeta, hostOptions, splits, walk } from "quario";
 import { bodyOf } from "./body.js";
-import { DOCUMENT_NS, furnish } from "./furniture.js";
+import { DOCUMENT_NS, furnish, NO_FURNITURE } from "./furniture.js";
 import { STYLES } from "./stylepart.js";
 import { DOCUMENT_PAGES, SECTION_PAGES } from "./text.js";
 import { geometry, pageBox, twips } from "./page.js";
 import { pack } from "./pack.js";
+import { overrides, packageRels, relationships } from "./rels.js";
 import { W, XML, esc } from "./xml.js";
 
-const RELS = 'xmlns="http://schemas.openxmlformats.org/package/2006/relationships"';
-const OFFICE = "http://schemas.openxmlformats.org/officeDocument/2006/relationships";
-const PACKAGE = "http://schemas.openxmlformats.org/package/2006/relationships";
 const WML = "application/vnd.openxmlformats-officedocument.wordprocessingml";
 
 // The distance from the paper's edge to a header or a footer, in twips: Word's
@@ -77,9 +73,9 @@ let core = (meta) =>
  *   refs: string, titlePg: boolean }} Section */
 
 // The parts every document relates to, in relationship order. A furniture part
-// numbers from after them, and both the content types and the relationships
-// below are one map over the pair, so a part cannot reach the package through
-// one and not the other.
+// numbers from after them, and `rels.js` maps the whole list to both the
+// content types and the relationships, so a part cannot reach the package
+// through one and not the other.
 // A picture's bytes are typed by extension rather than by part name, the way
 // `rels` and `xml` already are: one `Default` covers every image of that kind.
 const IMAGE_TYPES = [
@@ -88,20 +84,10 @@ const IMAGE_TYPES = [
 ];
 
 const FIXED = [
-  { path: "word/settings.xml", target: "settings.xml", kind: "settings", rId: "rId1" },
-  { path: "word/styles.xml", target: "styles.xml", kind: "styles", rId: "rId2" },
+  { target: "settings.xml", kind: "settings", rId: "rId1" },
+  { target: "styles.xml", kind: "styles", rId: "rId2" },
 ];
 
-// The content type of one furniture part, and the relationship that reaches
-// it. Both are keyed off the same `{ path, kind, rId }` the registry hands
-// back, so a part cannot reach the package through one and not the other.
-/** @type {(part: { path: string, kind: string }) => string} */
-let override = ({ path, kind }) =>
-  `<Override PartName="/${path}" ContentType="${WML}.${kind}+xml"/>`;
-/** @type {(part: { target: string, kind: string, rId: string }) => string} */
-let related = ({ target, kind, rId }) =>
-  `<Relationship Id="${rId}" Type="${OFFICE}/${kind}" Target="${target}"/>`;
-
 /**
  * The parts of the package. The floor is what Word opens: the content types,
  * the package relationships and `document.xml` — plus `settings.xml`, which is
@@ -118,7 +104,7 @@ let parts = (body, meta, furniture, rels) => ({
     '<Default Extension="rels" ContentType="application/vnd.openxmlformats-package.relationships+xml"/>' +
     '<Default Extension="xml" ContentType="application/xml"/>' +
     `<Override PartName="/word/document.xml" ContentType="${WML}.document.main+xml"/>` +
-    rels.map(override).join("") +
+    overrides(rels) +
     IMAGE_TYPES.filter(([ext]) => rels.some((r) => r.target.endsWith("." + ext)))
       .map(([ext, type]) => `<Default Extension="${ext}" ContentType="image/${type}"/>`)
       .join("") +
@@ -126,17 +112,9 @@ let parts = (body, meta, furniture, rels) => ({
       ? '<Override PartName="/docProps/core.xml" ContentType="application/vnd.openxmlformats-package.core-properties+xml"/>'
       : "") +
     "</Types>",
-  "_rels/.rels":
-    XML +
-    `<Relationships ${RELS}>` +
-    `<Relationship Id="rId1" Type="${OFFICE}/officeDocument" Target="word/document.xml"/>` +
-    (meta
-      ? `<Relationship Id="rId2" Type="${PACKAGE}/metadata/core-properties" Target="docProps/core.xml"/>`
-      : "") +
-    "</Relationships>",
+  "_rels/.rels": packageRels(meta),
   "word/document.xml": XML + `<w:document ${DOCUMENT_NS}><w:body>${body}</w:body></w:document>`,
-  "word/_rels/document.xml.rels":
-    XML + `<Relationships ${RELS}>` + rels.map(related).join("") + "</Relationships>",
+  "word/_rels/document.xml.rels": relationships(rels),
   "word/settings.xml":
     XML +
     `<w:settings ${W}><w:compat>` +
@@ -153,8 +131,6 @@ let parts = (body, meta, furniture, rels) => ({
  * bytes described in SCHEMA.md ("The DOCX target"). Options are taken and
  * validated at the factory call.
  *
- * The options are described once, in the hand-written public declarations,
- * and read back here -- a second copy in JSDoc is a copy that drifts.
  * @import { DocxOptions } from './index.d.ts'
  *
  * @param {DocxOptions} [options] Host controls (see SCHEMA.md, "The DOCX target").
@@ -176,33 +152,45 @@ 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
     // allocator, because a page band and the body both draw pictures and two
     // would hand out the same number twice.
-    /** @type {{ path: string, target: string, kind: string, rId: string }[]} */
+    /** @type {import('./rels.js').Rel[]} */
     let rels = [...FIXED];
     /** @type {Record<string, Uint8Array>} */
     let media = {};
     /** @type {(kind: string, target: string) => string} */
     let relate = (kind, target) => {
       let rId = "rId" + (rels.length + 1);
-      rels.push({ path: "word/" + target, target, kind, rId });
+      rels.push({ target, kind, rId });
       return rId;
     };
-    // One part per distinct picture. Keyed on the bytes themselves: the
+    // The one registry, handed to whatever writes a part: the furniture needs
+    // the records and not only the ids, because a part's own relationships are
+    // the ones its markup refers to.
+    let registry = { rels, relate };
+    // 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();
+    // One relationship per distinct URL, for the same reason: a report linking
+    // one place from every row would otherwise relate to it once per row.
+    /** @type {Map<string, string>} */
+    let linked = new Map();
+    /** @type {(url: string) => string} */
+    let link = (url) => {
+      let seen = linked.get(url);
+      if (seen) return seen;
+      let rId = relate("hyperlink", url);
+      linked.set(url, rId);
+      return rId;
+    };
     /** @type {(event: any) => string} */
     let picture = (event) => {
       let seen = drawn.get(event.bytes);
@@ -213,7 +201,7 @@ export function docx(options) {
       drawn.set(event.bytes, rId);
       return rId;
     };
-    let furniture = furnish();
+    let furniture = NO_FURNITURE;
 
     /** @type {(kind: any) => Section} */
     let section = (kind) => ({
@@ -221,20 +209,21 @@ export function docx(options) {
       ...furniture.refsFor(kind.reset ? SECTION_PAGES : DOCUMENT_PAGES),
     });
     let body = bodyOf(section);
-    await walk(stream(data), {
+    await walk(collapse(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 },
           width: geo.width - 2 * geo.margin,
           picture,
+          link,
         };
-        furniture = furnish(event.page, event.marking, relate, ctx);
+        furniture = furnish(event.page, event.marking ?? "", registry, ctx);
         body.start(ctx, event);
       },
     });
@@ -254,3 +243,53 @@ export function docx(options) {
   };
   return { name: "docx", compile };
 }
+
+/**
+ * What this target makes of each declaration the support matrix names: one of
+ * the [fates](../../../CONTEXT.md#declaration-and-resolution) — `resolved`,
+ * `approximated`, `withdrawn` or `unread` — so a host can ask before it
+ * renders rather than reading the prose.
+ *
+ * **Hand-written, and gated rather than generated.** SCHEMA.md's matrix is the
+ * description a person maintains and this is the data a host reads; the repo's
+ * `test/capabilities.test.js` holds the two equal, which is the same bargain
+ * ADR 0014 makes for the band-role table. It carries no version of its own:
+ * the package that ships it is the version, and a second copy could only drift
+ * from it.
+ *
+ * Keyed by the **schema name** an author writes, so a host, a `required`
+ * marking and a problem message all index by one vocabulary. Two rows share
+ * the bare word `width`, so each is qualified by what carries it.
+ *
+ * It covers the declarations every official target states one fate for. A
+ * matrix row that summarises more than one declaration, or that describes a
+ * behaviour rather than a declaration, states no single fate and is absent
+ * here — an absent key means the spec does not answer, never that this target
+ * has no answer.
+ */
+export const capabilities = Object.freeze({
+  target: "docx",
+  declarations: Object.freeze({
+    "page.header": "resolved",
+    "page.footer": "resolved",
+    break: "resolved",
+    reset: "resolved",
+    "page.margin": "resolved",
+    "header.height": "withdrawn",
+    groups: "resolved",
+    label: "approximated",
+    collapsed: "resolved",
+    "column.width": "approximated",
+    "slot.width": "resolved",
+    span: "resolved",
+    uppercase: "resolved",
+    href: "resolved",
+    spaceBefore: "resolved",
+    spaceAfter: "resolved",
+    format: "resolved",
+    family: "resolved",
+    valign: "resolved",
+    runs: "resolved",
+    alt: "resolved",
+  }),
+});

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

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}
  */