@quario/docx 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @quario/docx
 
+## 0.3.0
+
+### Minor Changes
+
+- **A `capabilities` descriptor.** The target exports what it makes of each declaration the spec's support matrix names — `resolved`, `approximated`, `withdrawn` or `unread` — beside its factory, so a host can ask before it renders rather than reading the prose. It is keyed by the schema name an author writes (`valign`, `break`, `page.margin`, and `column.width` / `slot.width` where one word carries two declarations), hand-written and gated against that matrix. It carries no version of its own: the package that ships it is the version.
+- **A run that carries an `href` is a Word hyperlink.** A URL becomes a relationship of the part the run lands in, marked as leaving the package, and one relationship serves every run pointing at the same place. An `href` beginning `#` becomes a `w:anchor`, and the first instance of the group carrying that `label` writes the bookmark it names, beside the heading that item already takes. A run whose text is empty writes no link and relates to nothing. The support matrix recorded this target as withdrawing `href`, and it now resolves it.
+
+  Two things a page band's own part had wrong are fixed with it. A header or footer now carries its **own relationships part**, so a picture or a link inside a band resolves in the part that refers to it rather than only in `document.xml`'s. And `[Content_Types].xml` no longer writes an `Override` for a relationship that names no WordprocessingML part. That entry typed a picture's bytes as a document part, which said nothing true about them.
+
+- **`negative` and `zero` reach the runs.** The target presents through the engine's `format()`, so a cell declaring either reads the same in Word as on the page.
+- **A collapsed group does not draw its content.** An instance whose group declares `collapsed` renders as its header and footer, with the rows between them left out — a page has nowhere to put a row a reader could open. Aggregates are unchanged, so a footer still totals them.
+- **The report header scales with the report default.** A report-header run is written at 1.4× the report default's size rather than a fixed 14, rounded to Word's half-points. A document declaring no size keeps its bytes, because 1.4× the base 10 is the same 14. A document declaring `"size": 20` now renders its report header at 28 where it rendered at 14, smaller than its own body.
+
+### Patch Changes
+
+- Updated dependencies
+  - quario@0.11.0
+
 ## 0.2.0
 
 ### Minor Changes

package/lib/body.js

@@ -34,12 +34,11 @@
  * written per run), the report default, the band-role default, then the node's
  * own. A `false` in an inner layer is a declaration and wins.
  */
-import { headingAt } from "./stylepart.js";
+import { BASE, headingAt } from "./stylepart.js";
 import { paraProps, under } from "./style.js";
 import { grid, record, tbl } from "./table.js";
 import { content, splitBlock } from "./content.js";
-import { EMPTY_CTX } from "./furniture.js";
-import { paragraph } from "./text.js";
+import { bookmark, 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
@@ -52,10 +51,21 @@ const BREAK = "<w:pageBreakBefore/>";
 // agreement; it is not shared code, and that is the ADR's point.
 /** @type {Record<string, any>} */
 const ROLES = {
-  "report-header": { bold: true, size: 14 },
+  "report-header": { bold: true, scale: 1.4 },
   "group-header": { bold: true },
 };
 
+// A role's default as a style block: `scale` is a factor over the report
+// default's size, or over the base the style part writes when the report
+// declared none, so a larger document keeps its headline larger.
+/** @type {(role: string, base: any) => any} */
+const roleStyle = (role, base) => {
+  let { scale, ...rest } = ROLES[role];
+  // The engine admits only a positive number, so absent is the one other case.
+  let size = base?.size || BASE;
+  return scale ? { ...rest, size: Math.round(scale * size * 100) / 100 } : rest;
+};
+
 // The cell padding this target supplies on a side the author did not name: 6 pt
 // across, 2 pt down, the layout's own numbers. A named `0` beats it, which is
 // what makes the declaration a declaration (`docs/adr/0040`).
@@ -91,16 +101,26 @@ export let bodyOf = (section) => {
   // paragraph carries one `spacing` element and the author may have declared
   // it -- so the gap layers under their own `spaceBefore`, which then wins.
   let owed = { broken: false, gapped: false };
-  // The heading a group instance's *first* header item is still owed, set when
-  // the instance opens and taken by whichever item claims it. One string rather
-  // than a depth and a flag: the two only ever moved together.
-  let heading = "";
+  // What a group instance's *first* header item is still owed, set when the
+  // instance opens and taken by whichever item claims it: the heading its depth
+  // earns, and the bookmark its `label` is the destination of. One record rather
+  // than a depth, a flag and a name: they only ever move together.
+  /** @type {{ props: string, mark: { id: number, name: string } | null }} */
+  let owes = { props: "", mark: null };
+  // The labels a destination has already been written for, and how many there
+  // are. A label two instances share is one destination and the first wins
+  // (SCHEMA.md, "Style declarations"), and Word's bookmark id is an integer the
+  // document uses once.
+  /** @type {Set<string>} */
+  let labelled = new Set();
   /** 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 —
    *  `content.js`'s `Ctx`, so the two writers describe a render one way.
+   *  Nothing reads it before then, which is why the picture registry the real
+   *  one carries is absent here rather than stubbed.
    *  @type {import("./content.js").Ctx} */
-  let ctx = EMPTY_CTX;
+  let ctx = /** @type {any} */ ({ base: null, intl: null, width: 0 });
   /** The table being filled, if any: its grid, and the rows written so far. */
   /** @type {{ widths: number[], rows: string } | null} */
   let table = null;
@@ -160,7 +180,7 @@ export let bodyOf = (section) => {
   /** @type {(event: any) => any} */
   let styleOf = (event) =>
     under(
-      under(ctx.base, Object.hasOwn(ROLES, event.role) ? ROLES[event.role] : null),
+      under(ctx.base, Object.hasOwn(ROLES, event.role) ? roleStyle(event.role, ctx.base) : null),
       event.style,
     );
 
@@ -191,7 +211,7 @@ export let bodyOf = (section) => {
    * @type {(event: any) => void}
    */
   let group = (event) => {
-    heading = `<w:pStyle w:val="${headingAt(event.depth)}"/>`;
+    owes = { props: `<w:pStyle w:val="${headingAt(event.depth)}"/>`, mark: marking(event.label) };
     // A structural half-line before every instance, dropped where the document
     // has not started: groups read as blocks without authored margins.
     // oxlint-disable-next-line no-unused-expressions
@@ -237,17 +257,27 @@ export let bodyOf = (section) => {
     if (frame) closeInstance(frame);
   };
 
+  /** The destination an instance's label is, or none where it declared none or
+   *  an earlier instance already carries it.
+   *  @type {(label: any) => { id: number, name: string } | null} */
+  let marking = (label) => {
+    if (!label || labelled.has(label)) return null;
+    labelled.add(label);
+    return { id: labelled.size, name: label };
+  };
+
   /**
-   * The paragraph properties an item's role earns: the heading its instance is
-   * owed, on a group instance's *first* header item, and nothing anywhere else.
+   * What an item's role earns from its instance: the heading and the bookmark
+   * it is owed, on a group instance's *first* header item, and nothing anywhere
+   * else.
    *
-   * @type {(role: string) => string}
+   * @type {(role: string) => { props: string, mark: { id: number, name: string } | null }}
    */
-  let claimHeading = (role) => {
-    if (role !== "group-header") return "";
-    let owes = heading;
-    heading = "";
-    return owes;
+  let claim = (role) => {
+    if (role !== "group-header") return { props: "", mark: null };
+    let owed = owes;
+    owes = { props: "", mark: null };
+    return owed;
   };
 
   /** How wide the body is where it is being written: the text column, divided
@@ -261,7 +291,8 @@ export let bodyOf = (section) => {
   /** @type {(event: any) => void} */
   let itemOf = (event) => {
     let style = styleOf(event);
-    push(claimHeading(event.role), style, content(event, style, columnWidth(), ctx));
+    let { props, mark } = claim(event.role);
+    push(props, style, bookmark(mark, content(event, style, columnWidth(), ctx)));
   };
 
   /** @type {(event: any) => void} */
@@ -269,10 +300,12 @@ export let bodyOf = (section) => {
     block(splitBlock(event, columnWidth(), styleOf(event), ctx));
   };
 
-  /** What a table's cells are written with. `intl` is settled on the opening
-   *  event, so it is read here rather than captured at compile.
-   *  @type {() => { pad: Record<string, number>, intl: any }} */
-  let ruled = () => ({ pad: PAD, intl: ctx.intl });
+  /** What a table's cells are written with. `intl` and the link registry are
+   *  settled on the opening event, so they are read here rather than captured
+   *  at compile.
+   *  @type {() => { pad: Record<string, number>, intl: any,
+   *    link: (url: string) => string }} */
+  let ruled = () => ({ pad: PAD, intl: ctx.intl, link: ctx.link });
 
   /** @type {(event: any) => void} */
   let tableStart = (event) => {

package/lib/content.js

@@ -12,13 +12,14 @@ 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.
+ * column a picture is capped at, the registries a picture's bytes and a link's
+ * URL become relationships 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
+ *   picture: (event: any) => string, link: (url: string) => string,
+ *   sequence?: string }} Ctx
  */
 
 /**
@@ -29,7 +30,7 @@ import { looking, runs } from "./text.js";
  * @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));
+  if (event.type !== "image") return runs(event.tokens, looking(style, ctx));
   let rId = ctx.picture(event);
   return drawing(event, idOf(rId), rId, describe(event), sizeOf(event, column));
 };

package/lib/furniture.js

@@ -22,6 +22,7 @@
 import { splits } from "quario";
 import { content, splitBlock } from "./content.js";
 import { paraProps, under } from "./style.js";
+import { relationships } from "./rels.js";
 import { paragraph, run } from "./text.js";
 import { R, W, XML } from "./xml.js";
 
@@ -46,7 +47,7 @@ const MARKING_LOOK = '<w:color w:val="808080"/><w:sz w:val="14"/>';
  */
 let banded = (events, ctx) => {
   let out = "";
-  for (let e of splits(events)) out += STEPS[e.type]?.(e, ctx) ?? "";
+  for (let e of splits(events)) out += STEPS[e.type](e, ctx);
   return out;
 };
 
@@ -89,14 +90,20 @@ let reading = (closure, at, lead, ctx) => lead + (closure ? banded(closure(at),
  * `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>} */
@@ -104,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;
   };
 
@@ -123,11 +147,11 @@ export let furnish = (page, marking, relate = () => "", ctx = EMPTY_CTX) => {
   // 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.
-  /** @type {(kind: string, pair: string[], titlePg: boolean) => string} */
+  /** @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);
   };
 
@@ -140,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: "" },
@@ -149,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,
@@ -161,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

@@ -9,18 +9,16 @@
  * 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, splits, 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
@@ -75,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 = [
@@ -86,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
@@ -116,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("") +
@@ -124,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>` +
@@ -178,16 +158,20 @@ export function docx(options) {
     // 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;
     };
+    // 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,
     // so the part stays identical and the furniture's dedup still collapses
@@ -195,6 +179,18 @@ export function docx(options) {
     // 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);
@@ -205,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) => ({
@@ -213,7 +209,7 @@ export function docx(options) {
       ...furniture.refsFor(kind.reset ? SECTION_PAGES : DOCUMENT_PAGES),
     });
     let body = bodyOf(section);
-    await walk(splits(stream(data)), {
+    await walk(collapse(splits(stream(data))), {
       ...body.handlers,
       "report-start": (event) => {
         geo = geometry(page, event);
@@ -225,8 +221,9 @@ export function docx(options) {
           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);
       },
     });
@@ -246,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/rels.js

@@ -0,0 +1,66 @@
+/**
+ * The package's relationships: what a part may reach, and the id it refers to
+ * it by. A relationship is per part, so `document.xml` has its own and so does
+ * every header and footer — a picture a page band draws is reachable from the
+ * band's part or from nowhere.
+ *
+ * Two things a relationship says beyond its target. A **hyperlink** names a URL
+ * rather than a part, so it says `TargetMode` and the package types no content
+ * for it. Every other kind reaches a part this target packs, and of those the
+ * WordprocessingML ones each need a content type of their own — a picture's
+ * bytes are typed by their extension instead, one entry however many pictures
+ * there are.
+ */
+import { 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 one kind whose target leaves the package. */
+const EXTERNAL = "hyperlink";
+
+/** The kinds whose target is a WordprocessingML part of this package. */
+const TYPED = new Set(["settings", "styles", "header", "footer"]);
+
+/** @typedef {{ target: string, kind: string, rId: string }} Rel */
+
+/** One relationship. The target is a part name this target wrote or a URL the
+ *  engine admitted, and the escape is the same one every other string goes
+ *  through on the way out.
+ *  @type {(rel: Rel) => string} */
+let related = ({ target, kind, rId }) =>
+  `<Relationship Id="${rId}" Type="${OFFICE}/${kind}" Target="${esc(target)}"` +
+  (kind === EXTERNAL ? ' TargetMode="External"' : "") +
+  "/>";
+
+/** One relationships part, whether the package's or one part's own.
+ *  @type {(rels: Rel[]) => string} */
+export let relationships = (rels) =>
+  XML + `<Relationships ${RELS}>` + rels.map(related).join("") + "</Relationships>";
+
+/** The content types the relationships of one package earn: one per
+ *  WordprocessingML part they reach.
+ *  @type {(rels: Rel[]) => string} */
+export let overrides = (rels) =>
+  rels
+    .filter(({ kind }) => TYPED.has(kind))
+    .map(
+      ({ target, kind }) =>
+        `<Override PartName="/word/${target}" ContentType="${WML}.${kind}+xml"/>`,
+    )
+    .join("");
+
+/** The package's own relationships: `document.xml`, and the metadata part a
+ *  host's `meta` wrote. Its two entries name types from two vocabularies, which
+ *  is why they are spelled here rather than through `related`.
+ *  @type {(meta: any) => string} */
+export let packageRels = (meta) =>
+  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>";

package/lib/stylepart.js

@@ -24,11 +24,13 @@
  */
 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.
+// The base. Arial is the name the sans generic maps to; `BASE` is the type
+// size in points, `sz` in half-points; 1.4 line spacing is `line` in 240ths
+// of a line, `auto` so a larger run still fits. The layout carries the same
+// 10 (docs/adr/0014).
 const FAMILY = "Arial";
-const SIZE = 20;
+export const BASE = 10;
+const SIZE = BASE * 2;
 const LINE = 336;
 
 /** Word caps the outline at nine levels, and so does the deepest style here. */

package/lib/table.js

@@ -63,7 +63,7 @@ let tc = (cell, width, body, pad) =>
   (cell.span > 1 ? `<w:gridSpan w:val="${cell.span}"/>` : "") +
   cellProps(cell.style, pad) +
   "</w:tcPr>" +
-  (body || "<w:p/>") +
+  body +
   "</w:tc>";
 
 /**
@@ -125,7 +125,7 @@ export let splitting = (slots, width, style) => {
   return {
     style,
     slot: (own, content) => {
-      let column = widths[at++] || 0;
+      let column = widths[at++];
       // `boxed: false`: the slot's box is the cell's, so the paragraph inside
       // it must not draw a second one.
       cells += tc(
@@ -142,12 +142,12 @@ export let splitting = (slots, width, 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.
+ * the column it has reached, since a span consumes more than one. It is also
+ * where a span becomes a count of at least one, so this one takes it as read.
  *
  * @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);
+let spanned = (widths, at, span) => widths.slice(at, at + span).reduce((sum, w) => sum + w, 0);
 
 /**
  * One row of cells, each wearing what the row layers over it and taking the
@@ -158,7 +158,8 @@ let spanned = (widths, at, span) =>
  * 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}
+ *   how: { pad: Record<string, number>, intl: any,
+ *     link: (url: string) => string }) => string}
  */
 export let record = (cells, widths, heading, layer, how) => {
   let at = 0;
@@ -171,7 +172,7 @@ export let record = (cells, widths, heading, layer, how) => {
       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))),
+      paragraph(paraProps(style, false), runs(cell.tokens, looking(style, how))),
       how.pad,
     );
     at += span;

package/lib/text.js

@@ -18,7 +18,7 @@
  */
 import { display, format, styledRuns } from "quario";
 import { capitals, runProps } from "./style.js";
-import { esc } from "./xml.js";
+import { R, esc } from "./xml.js";
 
 /** One paragraph, its properties already written.
  *  @type {(props: string, inner: string) => string} */
@@ -104,38 +104,90 @@ let shown = (token, look) => format(token.value, look.style, look.intl) ?? displ
 /**
  * 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.
+ * `format` configuration, which field gives the current sequence's length, and
+ * the registry a link's URL becomes a relationship in. 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
+ *   sequence: string, link: (url: string) => string }} Look
  */
 
-/** @type {(style: any, intl: any, sequence?: string, boxed?: boolean) => Look} */
-export let looking = (style, intl, sequence = DOCUMENT_PAGES, boxed = false) => ({
+/** A `Look` from what the render already carries — `content.js`'s `Ctx`, a
+ *  table's `how`, or an outer `Look`. A body cell names no sequence, because
+ *  only a page band binds the `page` anchor.
+ *  @type {(style: any, of: { intl: any, sequence?: string,
+ *    link: (url: string) => string }, boxed?: boolean) => Look} */
+export let looking = (style, of, boxed = false) => ({
   style,
   props: runProps(style, boxed),
   caps: capitals(style),
-  intl,
-  sequence,
+  intl: of.intl,
+  sequence: of.sequence || DOCUMENT_PAGES,
+  link: of.link,
 });
 
+/**
+ * A run that carries an [`href`](../../../SCHEMA.md#style-declarations), inside
+ * its hyperlink. The engine admitted the URL against the host's scheme
+ * allowlist before it crossed (`docs/adr/0085`), so this target escapes it like
+ * every other string and decides nothing about it.
+ *
+ * An `href` beginning `#` names a group's `label`, which is the bookmark below;
+ * anything else is a URL, and a URL leaves the package, so it is a relationship
+ * of the part the run lands in. A run with no text is no link: there would be
+ * nothing to click, and the relationship would reach out of the document for
+ * nobody.
+ *
+ * The relationship namespace is declared on the element that uses it, as the
+ * picture's `blip` declares it: a page band's part carries no `r` of its own,
+ * and a part that opened one only where a link happened to land would be a
+ * second rule about where a namespace comes from.
+ *
+ * @type {(inner: string, look: Look) => string}
+ */
+let linked = (inner, look) => {
+  let href = look.style?.href;
+  if (!href || !inner) return inner;
+  let at = href.startsWith("#")
+    ? `w:anchor="${esc(href.slice(1))}"`
+    : `${R} r:id="${look.link(href)}"`;
+  return `<w:hyperlink ${at}>` + inner + "</w:hyperlink>";
+};
+
+/**
+ * A destination inside the document: the bookmark an instance's
+ * [`label`](../../../SCHEMA.md#group-definition) names, around the content of
+ * the item that claimed it. The name is the label itself, which is what an
+ * `href` of `#label` asks for; the id is Word's own, an integer the document
+ * uses once.
+ *
+ * @type {(mark: { id: number, name: string } | null, inner: string) => string}
+ */
+export let bookmark = (mark, inner) =>
+  mark
+    ? `<w:bookmarkStart w:id="${mark.id}" w:name="${esc(mark.name)}"/>` +
+      inner +
+      `<w:bookmarkEnd w:id="${mark.id}"/>`
+    : inner;
+
 /**
  * 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.
+ * whatever style it wears. A run carrying an `href` sits inside its hyperlink,
+ * which is an element of the paragraph rather than a run property.
  *
  * @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
+      let own = styled.style ? looking(styled.style, look, true) : look;
+      let inner = styled.tokens
         .map((token) => fieldOf(token, own.sequence) || run(textOf(token, own), own.props))
         .join("");
+      return linked(inner, own);
     })
     .join("");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quario/docx",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Tiny, flow-based Word render target for quario. Real Word tables, a navigable outline, live page-number fields.",
   "keywords": [
     "csp",
@@ -33,12 +33,13 @@
     "access": "public"
   },
   "scripts": {
-    "check": "npm run size && npm test && npm run test:browser",
+    "check": "npm run size && npm test",
+    "coverage:check": "c8 report --src lib/ --temp-directory=../../coverage/tmp --reporter=text --check-coverage --100",
     "size": "size-limit",
-    "test": "npm run test:unit && npm run test:types",
+    "test": "npm run test:unit && npm run test:browser && npm run test:types && npm run coverage:check",
     "test:browser": "node test/browser/setup.js",
     "test:types": "tsc && attw --pack . --profile esm-only",
-    "test:unit": "node --disallow-code-generation-from-strings --test --test-concurrency=1 test/*.test.js",
+    "test:unit": "c8 --clean=false --src lib/ --reporter=none --temp-directory=../../coverage/tmp node --disallow-code-generation-from-strings --test --test-concurrency=1 test/*.test.js",
     "prepack": "node -e \"require('fs').copyFileSync('../../LICENSE','LICENSE')\"",
     "postpack": "node -e \"require('fs').rmSync('LICENSE',{force:true})\""
   },
@@ -48,12 +49,12 @@
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.18.3",
     "@size-limit/preset-small-lib": "^13.0.3",
-    "quario": "^0.10.0",
+    "quario": "^0.11.0",
     "size-limit": "^13.0.3",
     "typescript": "^7.0.2"
   },
   "peerDependencies": {
-    "quario": "^0.10.0"
+    "quario": "^0.11.0"
   },
   "size-limit": [
     {