werkmap 0.2.0 → 0.4.0

package/lib/index.js

@@ -1,18 +1,7 @@
 // werkmap — a write-only OOXML (.xlsx) writer.
 //
-// One entry point, `workbook`, returning a small mutable builder whose only
-// terminal is `bytes()`. Nothing here reads a .xlsx file, and nothing turns a
-// string into code: the package runs under a Content Security Policy that
-// permits no string-to-code execution, and its suite runs Node with
-// `--disallow-code-generation-from-strings`. The source itself is scanned for
-// the two constructs, so the words naming them appear nowhere below.
-//
-// Two promises shape almost every decision below. The same calls produce the
-// same bytes on the same runtime, so nothing consults a clock, a locale or a
-// random source, and every table is written in a fixed order. And every
-// element is emitted in the Open XML SDK's own child sequence, which costs
-// nothing here — the parts are assembled as strings in one pass — and removes
-// the ordering risk in readers whose tolerance nobody has measured.
+// One entry point, `workbook`, returning a mutable builder whose only terminal
+// is `bytes()`. Nothing here reads a .xlsx file.
 
 // ---------------------------------------------------------------- ZIP ----
 
@@ -57,6 +46,66 @@ const DOS_DATE = (1 << 5) | 1;
 const STORED = 0;
 const DEFLATED = 8;
 
+/**
+ * @typedef {{ method: number, sum: number, packed: Uint8Array, raw: Uint8Array, name: Uint8Array }} Packed
+ */
+
+/** @param {Packed} entry */
+const localHeader = ({ method, sum, packed, raw, name }) => {
+  const head = new DataView(new ArrayBuffer(30));
+  head.setUint32(0, 0x04034b50, true);
+  head.setUint16(4, 20, true);
+  head.setUint16(6, 0x0800, true); // the name is UTF-8
+  head.setUint16(8, method, true);
+  head.setUint16(10, DOS_TIME, true);
+  head.setUint16(12, DOS_DATE, true);
+  head.setUint32(14, sum, true);
+  head.setUint32(18, packed.length, true);
+  head.setUint32(22, raw.length, true);
+  head.setUint16(26, name.length, true);
+  return new Uint8Array(head.buffer);
+};
+
+/** @param {Packed} entry @param {number} offset */
+const centralRecord = ({ method, sum, packed, raw, name }, offset) => {
+  const record = new DataView(new ArrayBuffer(46));
+  record.setUint32(0, 0x02014b50, true);
+  record.setUint16(4, 20, true);
+  record.setUint16(6, 20, true);
+  record.setUint16(8, 0x0800, true);
+  record.setUint16(10, method, true);
+  record.setUint16(12, DOS_TIME, true);
+  record.setUint16(14, DOS_DATE, true);
+  record.setUint32(16, sum, true);
+  record.setUint32(20, packed.length, true);
+  record.setUint32(24, raw.length, true);
+  record.setUint16(28, name.length, true);
+  record.setUint32(42, offset, true);
+  return new Uint8Array(record.buffer);
+};
+
+/** @param {number} count @param {number} size @param {number} offset */
+const endRecord = (count, size, offset) => {
+  const end = new DataView(new ArrayBuffer(22));
+  end.setUint32(0, 0x06054b50, true);
+  end.setUint16(8, count, true);
+  end.setUint16(10, count, true);
+  end.setUint32(12, size, true);
+  end.setUint32(16, offset, true);
+  return new Uint8Array(end.buffer);
+};
+
+/** @param {ReadonlyArray<Uint8Array>} chunks */
+const concat = (chunks) => {
+  const bytes = new Uint8Array(chunks.reduce((total, chunk) => total + chunk.length, 0));
+  let at = 0;
+  for (const chunk of chunks) {
+    bytes.set(chunk, at);
+    at += chunk.length;
+  }
+  return bytes;
+};
+
 /**
  * @param {ReadonlyArray<{ name: string, body: Uint8Array, store?: boolean }>} entries
  * @returns {Promise<Uint8Array>}
@@ -68,58 +117,16 @@ const zip = async (entries) => {
 
   for (const entry of entries) {
     const raw = entry.body;
-    const packed = entry.store ? raw : await deflate(raw);
-    const method = entry.store ? STORED : DEFLATED;
+    const [packed, method] = entry.store ? [raw, STORED] : [await deflate(raw), DEFLATED];
     const name = utf8(entry.name);
-    const sum = crc32(raw);
-
-    const head = new DataView(new ArrayBuffer(30));
-    head.setUint32(0, 0x04034b50, true);
-    head.setUint16(4, 20, true);
-    head.setUint16(6, 0x0800, true); // the name is UTF-8
-    head.setUint16(8, method, true);
-    head.setUint16(10, DOS_TIME, true);
-    head.setUint16(12, DOS_DATE, true);
-    head.setUint32(14, sum, true);
-    head.setUint32(18, packed.length, true);
-    head.setUint32(22, raw.length, true);
-    head.setUint16(26, name.length, true);
-    local.push(new Uint8Array(head.buffer), name, packed);
-
-    const record = new DataView(new ArrayBuffer(46));
-    record.setUint32(0, 0x02014b50, true);
-    record.setUint16(4, 20, true);
-    record.setUint16(6, 20, true);
-    record.setUint16(8, 0x0800, true);
-    record.setUint16(10, method, true);
-    record.setUint16(12, DOS_TIME, true);
-    record.setUint16(14, DOS_DATE, true);
-    record.setUint32(16, sum, true);
-    record.setUint32(20, packed.length, true);
-    record.setUint32(24, raw.length, true);
-    record.setUint16(28, name.length, true);
-    record.setUint32(42, offset, true);
-    central.push(new Uint8Array(record.buffer), name);
-
+    const item = { method, sum: crc32(raw), packed, raw, name };
+    local.push(localHeader(item), name, packed);
+    central.push(centralRecord(item, offset), name);
     offset += 30 + name.length + packed.length;
   }
 
   const size = central.reduce((total, chunk) => total + chunk.length, 0);
-  const end = new DataView(new ArrayBuffer(22));
-  end.setUint32(0, 0x06054b50, true);
-  end.setUint16(8, entries.length, true);
-  end.setUint16(10, entries.length, true);
-  end.setUint32(12, size, true);
-  end.setUint32(16, offset, true);
-
-  const all = [...local, ...central, new Uint8Array(end.buffer)];
-  const bytes = new Uint8Array(all.reduce((total, chunk) => total + chunk.length, 0));
-  let at = 0;
-  for (const chunk of all) {
-    bytes.set(chunk, at);
-    at += chunk.length;
-  }
-  return bytes;
+  return concat([...local, ...central, endRecord(entries.length, size, offset)]);
 };
 
 // ---------------------------------------------------------------- XML ----
@@ -132,10 +139,8 @@ const REL = "http://schemas.openxmlformats.org/officeDocument/2006/relationships
 const CT = "application/vnd.openxmlformats-officedocument";
 
 // What XML 1.0 cannot carry at all: the C0 range except TAB, LF and CR, and
-// unpaired surrogates. These are stripped rather than thrown over. The text
-// reaching this writer has already passed its caller's own gates, and failing
-// a whole document over one stray byte in a customer's name is the wrong
-// trade — this is the one place leniency belongs.
+// unpaired surrogates. Stripped rather than thrown over — the one place
+// leniency belongs.
 const FORBIDDEN =
   // This expression exists to find exactly the control characters the rule
   // below warns about, which is the one case where it is wrong.
@@ -157,12 +162,75 @@ const esc = (text) =>
     .replace(/>/g, "&gt;")
     .replace(/"/g, "&quot;");
 
-// `xml:space="preserve"` goes on every `<t>` rather than only where the text
-// needs it: without it a reader is free to trim, and one rule is easier to
-// trust than a predicate over whitespace.
+// `xml:space="preserve"` goes on every `<t>`, not only where the text needs
+// it: one rule is easier to trust than a predicate over whitespace.
 /** @param {string} text */
 const textNode = (text) => `<t xml:space="preserve">${esc(text)}</t>`;
 
+// ---------------------------------------------------------- validation ----
+
+// Absent means the caller said nothing: `undefined` and `null` read the same
+// everywhere on this surface.
+/** @param {unknown} value */
+const absent = (value) => value === undefined || value === null;
+
+/**
+ * @param {unknown} value
+ * @param {string} where
+ * @param {string} expected what the message names when the value is not an object
+ * @returns {Record<string, unknown>}
+ */
+const requireRecord = (value, where, expected) => {
+  if (value === null || typeof value !== "object")
+    throw TypeError(`${where}: expected ${expected}, got ${JSON.stringify(value)}`);
+  return /** @type {Record<string, unknown>} */ (value);
+};
+
+/**
+ * @param {unknown} value
+ * @param {string} where
+ */
+const requireString = (value, where) => {
+  if (typeof value !== "string")
+    throw TypeError(`${where}: expected a string, got ${JSON.stringify(value)}`);
+  return value;
+};
+
+/**
+ * @param {unknown} value
+ * @param {string} where
+ * @param {string} fallback
+ */
+const requireText = (value, where, fallback) =>
+  value === undefined ? fallback : requireString(value, where);
+
+/**
+ * @param {unknown} value
+ * @param {string} where
+ */
+const requireNumber = (value, where) => {
+  if (typeof value !== "number" || !Number.isFinite(value))
+    throw RangeError(`${where}: expected a finite number, got ${JSON.stringify(value)}`);
+  return value;
+};
+
+/** @param {unknown} value @param {number} limit */
+const isIndex = (value, limit) =>
+  typeof value === "number" && Number.isInteger(value) && value >= 1 && value <= limit;
+
+/**
+ * @param {unknown} value
+ * @param {number} limit
+ * @param {string} where
+ */
+const requireIndex = (value, limit, where) => {
+  if (!isIndex(value, limit))
+    throw RangeError(
+      `${where}: expected an integer between 1 and ${limit}, got ${JSON.stringify(value)}`,
+    );
+  return /** @type {number} */ (value);
+};
+
 /**
  * One run of rich text, written in full: an OOXML run inherits nothing from
  * the cell font.
@@ -170,17 +238,12 @@ const textNode = (text) => `<t xml:space="preserve">${esc(text)}</t>`;
  * @param {string} at
  */
 const richRun = (run, at) => {
-  if (run === null || typeof run !== "object")
-    throw TypeError(`${at}: expected a { text, font } run, got ${JSON.stringify(run)}`);
-  const text = /** @type {Record<string, unknown>} */ (run).text;
-  if (typeof text !== "string")
-    throw TypeError(`${at}.text: expected a string, got ${JSON.stringify(text)}`);
-  const font = /** @type {Record<string, unknown>} */ (run).font;
-  const properties =
-    font === undefined || font === null
-      ? ""
-      : `<rPr>${runFontXml(/** @type {Record<string, unknown>} */ (font), `${at}.font`)}</rPr>`;
-  return `<r>${properties}${textNode(text)}</r>`;
+  const { text, font } = requireRecord(run, at, "a { text, font } run");
+  const body = textNode(requireString(text, `${at}.text`));
+  const properties = absent(font)
+    ? ""
+    : `<rPr>${runFontXml(/** @type {Record<string, unknown>} */ (font), `${at}.font`)}</rPr>`;
+  return `<r>${properties}${body}</r>`;
 };
 
 /**
@@ -205,14 +268,10 @@ const richKey = (runs, where) => {
 
 // ------------------------------------------------------------- values ----
 
-// Excel's 1900 date system counts from an epoch of 1899-12-30, which absorbs
-// its phantom 1900-02-29. The conversion is in UTC: a reader's own timezone
-// is never consulted, so one `Date` is one serial everywhere.
-//
-// The phantom day is real for serial 60 and nothing else. Excel shows 60 as
-// 1900-02-29, a day that never happened, so every date before 1900-03-01 sits
-// one lower than the 1899-12-30 epoch alone would put it. A writer that skips
-// this arithmetic moves 1900-02-28 onto the phantom day.
+// Excel's 1900 date system counts from an epoch of 1899-12-30, in UTC. The
+// phantom 1900-02-29 is serial 60, so every date before 1900-03-01 sits one
+// lower than that epoch alone would put it: skip this arithmetic and
+// 1900-02-28 lands on the phantom day.
 const EPOCH_OFFSET = 25569;
 const DAY = 86_400_000;
 const PHANTOM = 61;
@@ -299,8 +358,7 @@ const FIRST_CUSTOM = 164;
 
 /**
  * Interning by a canonical key, preserving first-seen order. Every style
- * table in the file is one of these, which is what makes identical fonts,
- * fills, borders and formats collapse to one entry each.
+ * table is one of these.
  */
 /**
  * @template T
@@ -318,8 +376,7 @@ const table = (initial) => {
   return {
     items,
     /**
-     * Arrow rather than a method, so `strings` below can pass it on by name:
-     * it closes over the table and never touches `this`.
+     * Arrow rather than a method, so `strings` below can pass it on by name.
      * @param {string} key
      * @param {() => T} make
      */
@@ -336,6 +393,15 @@ const table = (initial) => {
 
 // ------------------------------------------------------------- styles ----
 
+// The boolean half of a font, in the order `CT_Font` writes them.
+/** @type {ReadonlyArray<[string, string]>} */
+const FONT_FLAGS = [
+  ["bold", "<b/>"],
+  ["italic", "<i/>"],
+  ["strikethrough", "<strike/>"],
+  ["underline", "<u/>"],
+];
+
 /**
  * The font half of a style, written in the SDK's `CT_Font` sequence:
  * b i strike u sz color name.
@@ -343,14 +409,14 @@ const table = (initial) => {
  * @param {string} where
  */
 const fontXml = (font, where) => {
-  let out = "";
-  if (font.bold) out += "<b/>";
-  if (font.italic) out += "<i/>";
-  if (font.strikethrough) out += "<strike/>";
-  if (font.underline) out += "<u/>";
-  out += `<sz val="${font.size === undefined ? 11 : requireNumber(font.size, `${where}.size`)}"/>`;
-  if (font.color !== undefined) out += `<color rgb="${rgb(font.color, `${where}.color`)}"/>`;
-  return out + `<name val="${esc(requireText(font.name, `${where}.name`, "Calibri"))}"/>`;
+  const flags = FONT_FLAGS.filter(([key]) => font[key])
+    .map(([, tag]) => tag)
+    .join("");
+  const size = font.size === undefined ? 11 : requireNumber(font.size, `${where}.size`);
+  const colour =
+    font.color === undefined ? "" : `<color rgb="${rgb(font.color, `${where}.color`)}"/>`;
+  const name = esc(requireText(font.name, `${where}.name`, "Calibri"));
+  return `${flags}<sz val="${size}"/>${colour}<name val="${name}"/>`;
 };
 
 /**
@@ -368,100 +434,98 @@ const SIDES = ["left", "right", "top", "bottom"];
  * @param {Record<string, unknown>} border
  * @param {string} where
  */
-const borderXml = (border, where) => {
-  let out = "";
-  for (const side of SIDES) {
-    const edge = border[side];
-    if (edge === undefined || edge === null) {
-      out += `<${side}/>`;
-      continue;
-    }
-    const at = `${where}.${side}`;
-    const style = /** @type {Record<string, unknown>} */ (edge).style;
-    if (typeof style !== "string" || !BORDER_STYLES.has(style))
-      throw RangeError(
-        `${at}.style: expected thin, dashed or dotted, got ${JSON.stringify(style)}`,
-      );
-    const colour = /** @type {Record<string, unknown>} */ (edge).color;
-    out +=
-      colour === undefined
-        ? `<${side} style="${style}"/>`
-        : `<${side} style="${style}"><color rgb="${rgb(colour, `${at}.color`)}"/></${side}>`;
-  }
-  return out + "<diagonal/>";
+/**
+ * @param {unknown} style
+ * @param {string} at
+ */
+const edgeStyle = (style, at) => {
+  if (typeof style !== "string" || !BORDER_STYLES.has(style))
+    throw RangeError(`${at}.style: expected thin, dashed or dotted, got ${JSON.stringify(style)}`);
+  return style;
 };
 
-const HORIZONTAL = new Set(["left", "center", "right", "justify", "fill"]);
-const VERTICAL = new Set(["top", "center", "bottom", "justify"]);
+/**
+ * One side of a border. An absent side is written empty rather than skipped,
+ * because `CT_Border` lists all four in a fixed order.
+ * @param {string} side
+ * @param {unknown} edge
+ * @param {string} at
+ */
+const sideXml = (side, edge, at) => {
+  if (absent(edge)) return `<${side}/>`;
+  const style = edgeStyle(/** @type {Record<string, unknown>} */ (edge).style, at);
+  const colour = /** @type {Record<string, unknown>} */ (edge).color;
+  return colour === undefined
+    ? `<${side} style="${style}"/>`
+    : `<${side} style="${style}"><color rgb="${rgb(colour, `${at}.color`)}"/></${side}>`;
+};
 
 /**
- * @param {Record<string, unknown>} alignment
+ * @param {Record<string, unknown>} border
  * @param {string} where
  */
-const alignmentXml = (alignment, where) => {
-  let out = "";
-  if (alignment.horizontal !== undefined) {
-    const horizontal = /** @type {string} */ (alignment.horizontal);
-    if (!HORIZONTAL.has(horizontal))
-      throw RangeError(`${where}.horizontal: unknown alignment ${JSON.stringify(horizontal)}`);
-    out += ` horizontal="${horizontal}"`;
-  }
-  if (alignment.vertical !== undefined) {
-    const vertical = /** @type {string} */ (alignment.vertical);
-    if (!VERTICAL.has(vertical))
-      throw RangeError(`${where}.vertical: unknown alignment ${JSON.stringify(vertical)}`);
-    out += ` vertical="${vertical}"`;
-  }
-  if (alignment.wrapText) out += ' wrapText="1"';
-  return out;
-};
+const borderXml = (border, where) =>
+  SIDES.map((side) => sideXml(side, border[side], `${where}.${side}`)).join("") + "<diagonal/>";
+
+const HORIZONTAL = new Set(["left", "center", "right", "justify", "fill"]);
+const VERTICAL = new Set(["top", "center", "bottom", "justify"]);
 
 /**
+ * One alignment axis as its attribute, or nothing when the caller left it out.
  * @param {unknown} value
+ * @param {ReadonlySet<string>} known
+ * @param {string} axis
  * @param {string} where
- * @param {string} fallback
  */
-const requireText = (value, where, fallback) => {
-  if (value === undefined) return fallback;
-  if (typeof value !== "string")
-    throw TypeError(`${where}: expected a string, got ${JSON.stringify(value)}`);
-  return value;
+const axisXml = (value, known, axis, where) => {
+  if (value === undefined) return "";
+  const named = /** @type {string} */ (value);
+  if (!known.has(named))
+    throw RangeError(`${where}.${axis}: unknown alignment ${JSON.stringify(named)}`);
+  return ` ${axis}="${named}"`;
 };
 
 /**
- * @param {unknown} value
+ * @param {Record<string, unknown>} alignment
  * @param {string} where
  */
-const requireNumber = (value, where) => {
-  if (typeof value !== "number" || !Number.isFinite(value))
-    throw RangeError(`${where}: expected a finite number, got ${JSON.stringify(value)}`);
-  return value;
-};
+const alignmentXml = (alignment, where) =>
+  axisXml(alignment.horizontal, HORIZONTAL, "horizontal", where) +
+  axisXml(alignment.vertical, VERTICAL, "vertical", where) +
+  (alignment.wrapText ? ' wrapText="1"' : "");
 
 /**
  * @typedef {{ numFmtId: number, fontId: number, fillId: number, borderId: number, alignment: string }} Xf
  */
 
+// Which `apply*` flag each table id switches on, in the order `CT_Xf` lists
+// them. Alignment is not a table, so it is written apart.
+/** @type {ReadonlyArray<["numFmtId" | "fontId" | "fillId" | "borderId", string]>} */
+const APPLIES = [
+  ["numFmtId", "applyNumberFormat"],
+  ["fontId", "applyFont"],
+  ["fillId", "applyFill"],
+  ["borderId", "applyBorder"],
+];
+
 /**
  * One `xf`. Each `apply*` flag says which table this format actually reaches
  * into; a reader ignores a table entry the flag does not claim.
  * @param {Xf} xf
  */
 const xfXml = (xf) => {
-  let out = `<xf numFmtId="${xf.numFmtId}" fontId="${xf.fontId}" fillId="${xf.fillId}" borderId="${xf.borderId}" xfId="0"`;
-  if (xf.numFmtId !== 0) out += ' applyNumberFormat="1"';
-  if (xf.fontId !== 0) out += ' applyFont="1"';
-  if (xf.fillId !== 0) out += ' applyFill="1"';
-  if (xf.borderId !== 0) out += ' applyBorder="1"';
-  if (xf.alignment !== "") out += ' applyAlignment="1"';
-  return xf.alignment === "" ? out + "/>" : `${out}><alignment${xf.alignment}/></xf>`;
+  const ids = `numFmtId="${xf.numFmtId}" fontId="${xf.fontId}" fillId="${xf.fillId}" borderId="${xf.borderId}"`;
+  const applies = APPLIES.filter(([key]) => xf[key] !== 0)
+    .map(([, flag]) => ` ${flag}="1"`)
+    .join("");
+  if (xf.alignment === "") return `<xf ${ids} xfId="0"${applies}/>`;
+  return `<xf ${ids} xfId="0"${applies} applyAlignment="1"><alignment${xf.alignment}/></xf>`;
 };
 
 /**
- * The whole of `styles.xml`, and the interning behind it. Entry 0 of each
- * table is the default every unstyled cell points at; the two fills OOXML
- * reserves (`none`, `gray125`) are written whether or not anything uses them,
- * because readers index fills by position.
+ * The whole of `styles.xml`. Entry 0 of each table is the default every
+ * unstyled cell points at, and the two fills OOXML reserves (`none`,
+ * `gray125`) are always written, because readers index fills by position.
  */
 const stylesheet = () => {
   const numFmts = new Map();
@@ -483,11 +547,14 @@ const stylesheet = () => {
    * @param {(value: Record<string, unknown>) => [string, () => T]} describe
    */
   const optional = (part, into, describe) => {
-    if (part === undefined || part === null) return 0;
+    if (absent(part)) return 0;
     const [key, make] = describe(/** @type {Record<string, unknown>} */ (part));
     return into.intern(key, make);
   };
 
+  /** @param {string} code */
+  const knownFormat = (code) => BUILT_IN.get(code) ?? numFmts.get(code);
+
   /**
    * A format code a reader knows by id keeps that id; anything else is
    * interned from 164 up, in first-seen order.
@@ -495,12 +562,10 @@ const stylesheet = () => {
    * @param {string} where
    */
   const formatId = (code, where) => {
-    if (code === undefined || code === null) return 0;
+    if (absent(code)) return 0;
     if (typeof code !== "string")
       throw TypeError(`${where}: expected a format code, got ${JSON.stringify(code)}`);
-    const builtIn = BUILT_IN.get(code);
-    if (builtIn !== undefined) return builtIn;
-    const seen = numFmts.get(code);
+    const seen = knownFormat(code);
     if (seen !== undefined) return seen;
     const id = FIRST_CUSTOM + numFmts.size;
     numFmts.set(code, id);
@@ -514,7 +579,7 @@ const stylesheet = () => {
      * @returns {number}
      */
     intern(style, where) {
-      if (style === undefined || style === null) return 0;
+      if (absent(style)) return 0;
       if (typeof style !== "object")
         throw TypeError(`${where}: expected a style object, got ${JSON.stringify(style)}`);
 
@@ -536,13 +601,12 @@ const stylesheet = () => {
           JSON.stringify(border),
           () => `<border>${borderXml(border, `${where}.border`)}</border>`,
         ]),
-        alignment:
-          style.alignment === undefined || style.alignment === null
-            ? ""
-            : alignmentXml(
-                /** @type {Record<string, unknown>} */ (style.alignment),
-                `${where}.alignment`,
-              ),
+        alignment: absent(style.alignment)
+          ? ""
+          : alignmentXml(
+              /** @type {Record<string, unknown>} */ (style.alignment),
+              `${where}.alignment`,
+            ),
       };
       return formats.intern(JSON.stringify(record), () => record);
     },
@@ -571,10 +635,7 @@ const stylesheet = () => {
 
 // ------------------------------------------------------ shared strings ----
 
-/**
- * Text is always interned here rather than written inline. It is what Excel
- * itself writes, and a report's repeated labels are what it shrinks.
- */
+/** Text is always interned here rather than written inline. */
 const strings = () => {
   // The same interning the style tables use: one `si` per distinct piece of
   // text, in first-seen order.
@@ -618,28 +679,36 @@ const FURNITURE = 0.3;
 
 /**
  * `pageMargins` and `pageSetup`, or nothing at all. `pageMargins` has no
- * optional attributes, so asking for any margin means writing all six — the
- * two this surface does not take keep Excel's own gap for a header and a
- * footer.
+ * optional attributes, so any margin means writing all six; the two this
+ * surface does not take keep Excel's own header and footer gap.
  *
- * @param {{ margin?: number, size?: string, orientation?: string, fit?: boolean } | null} setup
+ * @param {{ margin?: number, size?: string, orientation?: string, fit?: boolean, titles?: number } | null} setup
  */
 const printXml = (setup) => {
   if (setup === null) return "";
-  let out = "";
-  if (setup.margin !== undefined) {
-    const inches = (setup.margin / POINTS_PER_INCH).toFixed(3);
-    out +=
-      `<pageMargins left="${inches}" right="${inches}" top="${inches}" bottom="${inches}"` +
-      ` header="${FURNITURE}" footer="${FURNITURE}"/>`;
-  }
+  const attributes = setupAttributes(setup);
+  return marginsXml(setup.margin) + (attributes === "" ? "" : `<pageSetup${attributes}/>`);
+};
+
+/** @param {number | undefined} margin in points */
+const marginsXml = (margin) => {
+  if (margin === undefined) return "";
+  const inches = (margin / POINTS_PER_INCH).toFixed(3);
+  return (
+    `<pageMargins left="${inches}" right="${inches}" top="${inches}" bottom="${inches}"` +
+    ` header="${FURNITURE}" footer="${FURNITURE}"/>`
+  );
+};
+
+/** @param {{ size?: string, orientation?: string, fit?: boolean }} setup */
+const setupAttributes = (setup) => {
   let attributes = "";
   if (setup.size !== undefined) attributes += ` paperSize="${PAPER.get(setup.size)}"`;
   if (setup.orientation !== undefined) attributes += ` orientation="${setup.orientation}"`;
   // `fitToHeight="0"` is what makes it *width* the document fits to: one page
   // across, as many down as it takes.
   if (setup.fit === true) attributes += ' fitToWidth="1" fitToHeight="0"';
-  return attributes === "" ? out : out + `<pageSetup${attributes}/>`;
+  return attributes;
 };
 
 // -------------------------------------------------------------- sheet ----
@@ -652,21 +721,248 @@ const NAME_LIMIT = 31;
 const MAX_ROW = 1_048_576;
 const MAX_COLUMN = 16_384;
 
+// Excel's ceiling for a column width, in the unit the format states it: a
+// count of characters of the default font, the number Excel's own width box
+// shows. Not pixels: that conversion runs through the default font's maximum
+// digit width, and any cell here may name a font of its own.
+const MAX_WIDTH = 255;
+
+// EMU per CSS pixel at 96 dpi.
+const EMU = 9525;
+
+/**
+ * A `Date` as the serial Excel stores. An invalid one has no serial to give.
+ * @param {Date} date
+ * @param {string} at
+ */
+const dateSerial = (date, at) => {
+  if (Number.isNaN(date.getTime()))
+    throw RangeError(`${at}: expected a valid Date, got an invalid one`);
+  return serial(date);
+};
+
 /**
+ * The shared-string index of a cell's text, plain or rich.
+ * @param {ReturnType<typeof strings>} sst
+ * @param {unknown} value
+ * @param {string} at
+ */
+const textIndex = (sst, value, at) => {
+  if (typeof value === "string")
+    return sst.intern("s" + value, () => `<si>${textNode(value)}</si>`);
+  if (Array.isArray(value)) return sst.intern(richKey(value, at), () => richXml(value, at));
+  throw TypeError(`${at}: unsupported cell value ${JSON.stringify(value)}`);
+};
+
+/**
+ * The type attribute and `<v>` of a present cell value.
+ * @param {ReturnType<typeof strings>} sst
  * @param {unknown} value
- * @param {number} limit
  * @param {string} where
+ * @returns {[string, string | number]}
  */
-const requireIndex = (value, limit, where) => {
-  if (typeof value !== "number" || !Number.isInteger(value) || value < 1 || value > limit)
+const cellBody = (sst, value, where) => {
+  const at = `${where}.value`;
+  if (typeof value === "number") return ["", number(requireNumber(value, at))];
+  if (typeof value === "boolean") return [' t="b"', Number(value)];
+  if (value instanceof Date) return ["", number(dateSerial(value, at))];
+  return [' t="s"', textIndex(sst, value, at)];
+};
+
+/**
+ * @param {ReturnType<typeof strings>} sst
+ * @param {unknown} value
+ * @param {number} styleId
+ * @param {string} ref
+ * @param {string} where
+ */
+const cellXml = (sst, value, styleId, ref, where) => {
+  const s = styleId === 0 ? "" : ` s="${styleId}"`;
+  if (absent(value)) return s === "" ? "" : `<c r="${ref}"${s}/>`;
+  const [type, v] = cellBody(sst, value, where);
+  return `<c r="${ref}"${s}${type}><v>${v}</v></c>`;
+};
+
+// A style that is not an object passes through untouched, so the interning
+// below is still the one place that refuses it.
+/** @param {unknown} declared */
+const usable = (declared) => absent(declared) || typeof declared === "object";
+
+// A declared style that names no number format of its own.
+/** @param {Record<string, unknown> | null | undefined} declared */
+const undated = (declared) => usable(declared) && absent(declared?.numberFormat);
+
+/**
+ * A date with no format of its own gets the short-date built-in, so a `Date`
+ * reads back as a day rather than as the number underneath it.
+ * @param {unknown} value
+ * @param {Record<string, unknown> | null | undefined} declared
+ */
+const cellStyle = (value, declared) =>
+  value instanceof Date && undated(declared) ? { ...declared, numberFormat: SHORT_DATE } : declared;
+
+/** @param {number} frozen */
+const paneXml = (frozen) =>
+  frozen === 0
+    ? '<sheetView workbookViewId="0"/>'
+    : `<sheetView workbookViewId="0"><pane ySplit="${frozen}" topLeftCell="A${frozen + 1}" activePane="bottomLeft" state="frozen"/><selection pane="bottomLeft" activeCell="A${frozen + 1}" sqref="A${frozen + 1}"/></sheetView>`;
+
+/**
+ * @typedef {{ top: number, left: number, bottom: number, right: number }} Range
+ */
+
+/** @param {Range} range */
+const rangeRef = (range) =>
+  `${letters(range.left)}${range.top}:${letters(range.right)}${range.bottom}`;
+
+/** @param {Range} a @param {Range} b */
+const overlaps = (a, b) =>
+  a.top <= b.bottom && a.bottom >= b.top && a.left <= b.right && a.right >= b.left;
+
+/**
+ * A `<col>` per column that was given a width, in column order, and nothing
+ * at all when none was. One element apiece rather than a `min`/`max` run: a
+ * run may never span a column left unset, and the sparse case breaks that
+ * first, for bytes on one of the smallest parts here.
+ *
+ * `customWidth` is not optional. Without it a reader treats the width as one
+ * it derived, and is free to compute its own instead.
+ *
+ * @param {ReadonlyArray<number | null | undefined>} columns
+ */
+const colsXml = (columns) => {
+  const body = columns
+    .map((width, index) =>
+      absent(width)
+        ? ""
+        : `<col min="${index + 1}" max="${index + 1}" width="${number(width)}" customWidth="1"/>`,
+    )
+    .join("");
+  return body === "" ? "" : `<cols>${body}</cols>`;
+};
+
+// One rule of a filter's range, stated the way a caller reads it.
+/** @param {boolean} ok @param {string} why */
+const requireFilterRule = (ok, why) => {
+  if (!ok) throw RangeError(`filter: ${why}`);
+};
+
+// A range may only cover cells that were written. `merge` and `filter` both
+// ask it, of a row and of a column.
+/** @param {number} at @param {number} written @param {string} what @param {string} where */
+const requireWritten = (at, written, what, where) => {
+  if (at > written)
+    throw RangeError(`${where}: ${what} ${at} does not exist yet (the sheet has ${written})`);
+};
+
+/**
+ * The rectangle an autofilter covers, 1-based and inclusive on all four
+ * sides. A range whose bottom row was never written is a caller's bug, so
+ * this takes the row count to check it against.
+ *
+ * @param {unknown} range
+ * @param {number} rows how many rows the sheet holds
+ * @param {number} columns how many columns it has written
+ */
+const requireFilter = (range, rows, columns) => {
+  const rect = requireRecord(range, "filter", "{ top, left, bottom, right }");
+  const top = requireIndex(rect.top, MAX_ROW, "filter: top");
+  const left = requireIndex(rect.left, MAX_COLUMN, "filter: left");
+  const bottom = requireIndex(rect.bottom, MAX_ROW, "filter: bottom");
+  const right = requireIndex(rect.right, MAX_COLUMN, "filter: right");
+  requireFilterRule(bottom >= top, `bottom ${bottom} is above top ${top}`);
+  requireFilterRule(right >= left, `right ${right} is left of left ${left}`);
+  requireWritten(bottom, rows, "row", "filter");
+  requireWritten(right, columns, "column", "filter");
+  return { top, left, bottom, right };
+};
+
+/** @param {ReadonlyArray<Range>} merges */
+const mergesXml = (merges) =>
+  merges.length === 0
+    ? ""
+    : `<mergeCells count="${merges.length}">` +
+      merges.map((range) => `<mergeCell ref="${rangeRef(range)}"/>`).join("") +
+      `</mergeCells>`;
+
+/**
+ * The last column a merge reaches, once its width is known to be a count of
+ * two or more that stays on the sheet.
+ * @param {unknown} width
+ * @param {number} at
+ */
+const mergeEnd = (width, at) => {
+  if (!Number.isInteger(width) || /** @type {number} */ (width) < 2)
+    throw RangeError(`merge: expected a width of 2 or more, got ${JSON.stringify(width)}`);
+  const right = at + /** @type {number} */ (width) - 1;
+  if (right > MAX_COLUMN) throw RangeError(`merge: the range ends past column ${MAX_COLUMN}`);
+  return right;
+};
+
+/**
+ * One entry of a width list. Absent is how a caller leaves a column alone, so
+ * it is the one value that checks nothing.
+ *
+ * @param {unknown} width
+ * @param {number} index 0-based, so the message can name the column
+ */
+const checkWidth = (width, index) => {
+  if (absent(width)) return;
+  const chars = requireNumber(width, `widths: column ${index + 1}`);
+  if (chars > 0 && chars <= MAX_WIDTH) return;
+  throw RangeError(
+    `widths: column ${index + 1} expected a width above 0 and at most ${MAX_WIDTH}, got ${chars}` +
+      ` -- null leaves a column unset`,
+  );
+};
+
+/** @param {unknown} margin */
+const requireMargin = (margin) => {
+  const points = requireNumber(margin, "print: margin");
+  if (points < 0) throw RangeError(`print: margin cannot be negative, got ${points}`);
+};
+
+/** @param {unknown} size */
+const requirePaper = (size) => {
+  if (!PAPER.has(/** @type {string} */ (size)))
     throw RangeError(
-      `${where}: expected an integer between 1 and ${limit}, got ${JSON.stringify(value)}`,
+      `print: unknown paper size ${JSON.stringify(size)} -- known: ${[...PAPER.keys()].join(", ")}`,
     );
-  return value;
 };
 
-// EMU per CSS pixel at 96 dpi.
-const EMU = 9525;
+// Zero clears, as it does for a freeze, so a caller that set a count has a way
+// back. Not `requireIndex`: its message names 1 as the floor, and here it is 0.
+/** @param {unknown} rows */
+const requireTitles = (rows) => {
+  if (rows === 0) return;
+  if (!isIndex(rows, MAX_ROW))
+    throw RangeError(
+      `print: titles expected 0, or a row count between 1 and ${MAX_ROW}, got ${JSON.stringify(rows)}`,
+    );
+};
+
+/** @param {unknown} orientation */
+const requireOrientation = (orientation) => {
+  if (!ORIENTATION.has(/** @type {string} */ (orientation)))
+    throw RangeError(`print: expected portrait or landscape, got ${JSON.stringify(orientation)}`);
+};
+
+/** @param {number} width @param {number} height */
+const requireSize = (width, height) => {
+  if (width <= 0 || height <= 0)
+    throw RangeError(`place: expected a positive size, got ${width} by ${height}`);
+};
+
+// Every print key this surface checks, and the check it gets. Key order is
+// the order a caller hears about a mistake. A table rather than a run of
+// guards: a guard apiece puts `print` over the cyclomatic ceiling. `fit` is
+// absent because only `true` writes anything.
+const PRINT_CHECKS = {
+  margin: requireMargin,
+  size: requirePaper,
+  orientation: requireOrientation,
+  titles: requireTitles,
+};
 
 /**
  * One worksheet. Rows accumulate in call order; everything else is bookkeeping
@@ -686,48 +982,34 @@ const worksheet = (name, styles, sst, knows) => {
   const pictures = [];
   let frozen = 0;
   let widest = 1;
+  // This sheet's `autoFilter` element, or the empty string for a sheet that
+  // asked for none. Rendered where it is set, the way a row is.
+  let filtered = "";
+  // Widths by position, the first entry being column A. Replaced wholesale by
+  // `widths`, never merged: a hole in a positional list cannot mean both
+  // "leave this one alone" and "clear it".
+  /** @type {ReadonlyArray<number | null | undefined>} */
+  let columns = [];
   // What `print` was told, or null. Nothing reaches the file until a caller
   // asks: a reader's own print defaults are better than this writer guessing.
-  /** @type {{ margin?: number, size?: string, orientation?: string, fit?: boolean } | null} */
+  /** @type {{ margin?: number, size?: string, orientation?: string, fit?: boolean, titles?: number } | null} */
   let printing = null;
 
   /**
-   * @param {unknown} value
-   * @param {number} styleId
-   * @param {string} ref
-   * @param {string} where
+   * One cell of a row: the empty string for a gap, else its `<c>`.
+   * @param {unknown} cell
+   * @param {number} index 0-based column
+   * @param {number} at 1-based row
    */
-  const cellXml = (value, styleId, ref, where) => {
-    const s = styleId === 0 ? "" : ` s="${styleId}"`;
-
-    if (value === undefined || value === null) return s === "" ? "" : `<c r="${ref}"${s}/>`;
-
-    if (typeof value === "number") {
-      requireNumber(value, `${where}.value`);
-      return `<c r="${ref}"${s}><v>${number(value)}</v></c>`;
-    }
-
-    if (typeof value === "boolean") return `<c r="${ref}"${s} t="b"><v>${value ? 1 : 0}</v></c>`;
-
-    if (value instanceof Date) {
-      if (Number.isNaN(value.getTime()))
-        throw RangeError(`${where}.value: expected a valid Date, got an invalid one`);
-      return `<c r="${ref}"${s}><v>${number(serial(value))}</v></c>`;
-    }
-
-    if (typeof value === "string") {
-      const at = sst.intern("s" + value, () => `<si>${textNode(value)}</si>`);
-      return `<c r="${ref}"${s} t="s"><v>${at}</v></c>`;
-    }
-
-    if (Array.isArray(value)) {
-      const at = sst.intern(richKey(value, `${where}.value`), () =>
-        richXml(value, `${where}.value`),
-      );
-      return `<c r="${ref}"${s} t="s"><v>${at}</v></c>`;
-    }
-
-    throw TypeError(`${where}.value: unsupported cell value ${JSON.stringify(value)}`);
+  const cellAt = (cell, index, at) => {
+    if (absent(cell)) return "";
+    if (typeof cell !== "object")
+      throw TypeError(`row: cell ${index + 1} is not a { value, style } object`);
+    const where = `row ${at}, cell ${index + 1}`;
+    const { value, style } = /** @type {Record<string, unknown>} */ (cell);
+    const declared = /** @type {Record<string, unknown> | null | undefined} */ (style);
+    const styleId = styles.intern(cellStyle(value, declared), `${where}.style`);
+    return cellXml(sst, value, styleId, letters(index + 1) + at, where);
   };
 
   return {
@@ -742,35 +1024,8 @@ const worksheet = (name, styles, sst, knows) => {
         throw RangeError(`row: a sheet holds at most ${MAX_COLUMN} columns`);
 
       let body = "";
-      for (let index = 0; index < cells.length; index++) {
-        const cell = cells[index];
-        if (cell === undefined || cell === null) continue;
-        if (typeof cell !== "object")
-          throw TypeError(`row: cell ${index + 1} is not a { value, style } object`);
-        const where = `row ${at}, cell ${index + 1}`;
-        const declared = /** @type {Record<string, unknown> | null | undefined} */ (
-          /** @type {Record<string, unknown>} */ (cell).style
-        );
-        // A date with no format of its own gets the short-date built-in, so a
-        // `Date` reads back as a day rather than as the number underneath it.
-        // A style that is not an object passes through untouched, so the
-        // interning below is still the one place that refuses it.
-        const usable = declared === null || declared === undefined || typeof declared === "object";
-        const style =
-          /** @type {Record<string, unknown>} */ (cell).value instanceof Date &&
-          usable &&
-          (declared?.numberFormat ?? null) === null
-            ? { ...declared, numberFormat: SHORT_DATE }
-            : /** @type {Record<string, unknown> | null | undefined} */ (declared);
-        const styleId = styles.intern(style, `${where}.style`);
-        body += cellXml(
-          /** @type {Record<string, unknown>} */ (cell).value,
-          styleId,
-          letters(index + 1) + at,
-          where,
-        );
-      }
-      if (cells.length > widest) widest = cells.length;
+      for (let index = 0; index < cells.length; index++) body += cellAt(cells[index], index, at);
+      widest = Math.max(widest, cells.length);
       rows.push(`<row r="${at}">${body}</row>`);
       return at;
     },
@@ -783,67 +1038,91 @@ const worksheet = (name, styles, sst, knows) => {
     merge(row, at, width) {
       requireIndex(row, MAX_ROW, "merge: row");
       requireIndex(at, MAX_COLUMN, "merge: at");
-      if (row > rows.length)
-        throw RangeError(`merge: row ${row} does not exist yet (the sheet has ${rows.length})`);
-      if (typeof width !== "number" || !Number.isInteger(width) || width < 2)
-        throw RangeError(`merge: expected a width of 2 or more, got ${JSON.stringify(width)}`);
-      const right = at + width - 1;
-      if (right > MAX_COLUMN) throw RangeError(`merge: the range ends past column ${MAX_COLUMN}`);
-      for (const other of merges)
-        if (row >= other.top && row <= other.bottom && at <= other.right && right >= other.left)
-          throw RangeError(
-            `merge: the range ${letters(at)}${row}:${letters(right)}${row} overlaps ` +
-              `${letters(other.left)}${other.top}:${letters(other.right)}${other.bottom}`,
-          );
-      merges.push({ top: row, left: at, bottom: row, right });
-      if (right > widest) widest = right;
+      requireWritten(row, rows.length, "row", "merge");
+      const range = { top: row, left: at, bottom: row, right: mergeEnd(width, at) };
+      const clash = merges.find((other) => overlaps(range, other));
+      if (clash !== undefined)
+        throw RangeError(`merge: the range ${rangeRef(range)} overlaps ${rangeRef(clash)}`);
+      merges.push(range);
+      widest = Math.max(widest, range.right);
     },
 
     /**
      * How this worksheet prints. Every key is optional, and a worksheet that
-     * never calls this carries no print setup at all — a reader's own defaults
-     * are better than a guess, and writing one would put this writer's opinion
-     * in every file.
+     * never calls this carries no print setup at all: a reader's own defaults
+     * beat a guess.
      *
-     * @param {{ margin?: number, size?: string, orientation?: string, fit?: boolean }} setup
+     * @param {{ margin?: number, size?: string, orientation?: string, fit?: boolean, titles?: number }} setup
      */
     print(setup) {
-      if (setup === null || typeof setup !== "object")
-        throw TypeError(`print: expected a setup object, got ${JSON.stringify(setup)}`);
-      if (setup.margin !== undefined && requireNumber(setup.margin, "print: margin") < 0)
-        throw RangeError(`print: margin cannot be negative, got ${setup.margin}`);
-      if (setup.size !== undefined && !PAPER.has(setup.size))
-        throw RangeError(
-          `print: unknown paper size ${JSON.stringify(setup.size)} -- known: ${[...PAPER.keys()].join(", ")}`,
-        );
-      if (setup.orientation !== undefined && !ORIENTATION.has(setup.orientation))
-        throw RangeError(
-          `print: expected portrait or landscape, got ${JSON.stringify(setup.orientation)}`,
-        );
+      const declared = requireRecord(setup, "print", "a setup object");
+      for (const [key, check] of Object.entries(PRINT_CHECKS))
+        if (declared[key] !== undefined) check(declared[key]);
       printing = { ...printing, ...setup };
     },
 
+    // Read by the workbook part rather than by this sheet's own: a print title
+    // is a defined name, and defined names live in `xl/workbook.xml`.
+    get titles() {
+      return printing?.titles ?? 0;
+    },
+
     /** @param {number} count */
     freeze(count) {
-      if (typeof count !== "number" || !Number.isInteger(count) || count < 0 || count >= MAX_ROW)
+      if (!Number.isInteger(count) || count < 0 || count >= MAX_ROW)
         throw RangeError(`freeze: expected a row count of 0 or more, got ${JSON.stringify(count)}`);
       frozen = count;
     },
 
+    /**
+     * Column widths by position, the first entry being column A. `null` leaves
+     * a column unset, so a reader keeps its own default for it.
+     *
+     * Replaces rather than merges, and an empty list clears. A width never
+     * widens the sheet: `dimension` describes the cells that were written, and
+     * sizing a column writes no cell.
+     *
+     * @param {ReadonlyArray<unknown>} list
+     */
+    widths(list) {
+      if (!Array.isArray(list))
+        throw TypeError(`widths: expected an array of widths, got ${JSON.stringify(list)}`);
+      if (list.length > MAX_COLUMN)
+        throw RangeError(`widths: a sheet holds at most ${MAX_COLUMN} columns`);
+      list.forEach(checkWidth);
+      columns = list.slice();
+    },
+
+    /**
+     * Put an autofilter over a range, 1-based and inclusive. A worksheet takes
+     * one, so this replaces rather than merges, and `null` clears it.
+     *
+     * @param {unknown} range
+     */
+    filter(range) {
+      // Excel also records an autofilter as a sheet-scoped
+      // `_xlnm._FilterDatabase` defined name; this writes none. Measured in
+      // both readers: Excel opens such a file with no repair prompt and
+      // reports the filter as on, and LibreOffice writes the name itself on
+      // save. The name is a reader's bookkeeping.
+      filtered =
+        range === null
+          ? ""
+          : `<autoFilter ref="${rangeRef(requireFilter(range, rows.length, widest))}"/>`;
+    },
+
     /**
      * @param {unknown} id
      * @param {{ row: number, col?: number, width: number, height: number }} at
      */
     place(id, at) {
       if (!knows(id)) throw TypeError(`place: no image with id ${JSON.stringify(id)}`);
-      if (at === null || typeof at !== "object")
-        throw TypeError(`place: expected { row, col, width, height }, got ${JSON.stringify(at)}`);
+      requireRecord(at, "place", "{ row, col, width, height }");
       const row = requireIndex(at.row, MAX_ROW, "place: row");
       const col = requireIndex(at.col === undefined ? 1 : at.col, MAX_COLUMN, "place: col");
       const width = requireNumber(at.width, "place: width");
       const height = requireNumber(at.height, "place: height");
-      if (width <= 0 || height <= 0)
-        throw RangeError(`place: expected a positive size, got ${width} by ${height}`);
+      requireSize(width, height);
       pictures.push({ id: /** @type {number} */ (id), row, col, width, height });
     },
 
@@ -854,21 +1133,6 @@ const worksheet = (name, styles, sst, knows) => {
     /** @param {number | null} drawing the relationship id of this sheet's drawing part */
     xml(drawing) {
       const dimension = `A1:${letters(widest)}${Math.max(rows.length, 1)}`;
-      const pane =
-        frozen === 0
-          ? '<sheetView workbookViewId="0"/>'
-          : `<sheetView workbookViewId="0"><pane ySplit="${frozen}" topLeftCell="A${frozen + 1}" activePane="bottomLeft" state="frozen"/><selection pane="bottomLeft" activeCell="A${frozen + 1}" sqref="A${frozen + 1}"/></sheetView>`;
-      const merged =
-        merges.length === 0
-          ? ""
-          : `<mergeCells count="${merges.length}">` +
-            merges
-              .map(
-                (range) =>
-                  `<mergeCell ref="${letters(range.left)}${range.top}:${letters(range.right)}${range.bottom}"/>`,
-              )
-              .join("") +
-            `</mergeCells>`;
 
       // `fitToPage` lives on `sheetPr`, which the schema puts before every
       // other child of a worksheet.
@@ -880,9 +1144,11 @@ const worksheet = (name, styles, sst, knows) => {
         `<worksheet xmlns="${NS}" xmlns:r="${NS_R}">` +
         properties +
         `<dimension ref="${dimension}"/>` +
-        `<sheetViews>${pane}</sheetViews>` +
+        `<sheetViews>${paneXml(frozen)}</sheetViews>` +
+        colsXml(columns) +
         `<sheetData>${rows.join("")}</sheetData>` +
-        merged +
+        filtered +
+        mergesXml(merges) +
         printXml(printing) +
         (drawing === null ? "" : `<drawing r:id="rId${drawing}"/>`) +
         `</worksheet>`
@@ -892,10 +1158,9 @@ const worksheet = (name, styles, sst, knows) => {
 };
 
 /**
- * The drawing part for one sheet: a `oneCellAnchor` per placement, anchored to
- * the top-left of its cell at the size the caller asked for. The XML counts
- * rows and columns from zero and the subtraction happens here, so the surface
- * stays 1-based throughout.
+ * The drawing part for one sheet: a `oneCellAnchor` per placement, anchored
+ * to the top-left of its cell. The XML counts rows and columns from zero and
+ * the subtraction happens here, so the surface stays 1-based throughout.
  *
  * @param {ReturnType<typeof worksheet>["pictures"]} pictures
  * @param {ReadonlyArray<number>} media the media index each picture points at
@@ -935,26 +1200,214 @@ const FORMATS = new Map([
 // "the same input" as "the same input at the same wall time".
 const CREATED = "1970-01-01T00:00:00Z";
 
-/** @param {Uint8Array} a @param {Uint8Array} b */
-const same = (a, b) => {
-  // The same array twice is the common case, and the one the byte loop is
-  // worst at: equal bytes never exit early, so it reads the whole image every
-  // time. A caller placing one logo on a thousand rows pays 54 ms for that,
-  // and nothing for this.
-  if (a === b) return true;
-  if (a.length !== b.length) return false;
+/** @param {Uint8Array} a @param {Uint8Array} b of the same length */
+const sameBytes = (a, b) => {
   for (let at = 0; at < a.length; at++) if (a[at] !== b[at]) return false;
   return true;
 };
 
+// The same array twice is the common case, and the one the byte loop is worst
+// at: equal bytes never exit early, so it reads the whole image every time. A
+// caller placing one logo on a thousand rows pays 54 ms for that, and nothing
+// for the identity check.
+/** @param {Uint8Array} a @param {Uint8Array} b */
+const same = (a, b) => a === b || (a.length === b.length && sameBytes(a, b));
+
+/**
+ * @param {unknown} name
+ * @returns {string}
+ */
+const requireSheetName = (name) => {
+  if (typeof name !== "string" || name === "")
+    throw RangeError(`sheet: expected a name, got ${JSON.stringify(name)}`);
+  if (name.length > NAME_LIMIT)
+    throw RangeError(`sheet: a name is at most ${NAME_LIMIT} characters, got ${name.length}`);
+  return name;
+};
+
+/**
+ * @param {number} sheets how many worksheets the workbook holds
+ * @param {number} drawings how many of them carry a drawing part
+ * @param {ReadonlyArray<{ format: string }>} media
+ */
+const contentTypesXml = (sheets, drawings, media) => {
+  const overrides = Array.from(
+    { length: sheets },
+    (_sheet, index) =>
+      `<Override PartName="/xl/worksheets/sheet${index + 1}.xml" ContentType="${CT}.spreadsheetml.worksheet+xml"/>`,
+  ).join("");
+  const drawingOverrides = Array.from(
+    { length: drawings },
+    (_each, at) =>
+      `<Override PartName="/xl/drawings/drawing${at + 1}.xml" ContentType="${CT}.drawing+xml"/>`,
+  ).join("");
+  const defaults = [...new Set(media.map((each) => each.format))]
+    .map((format) => `<Default Extension="${format}" ContentType="${FORMATS.get(format)}"/>`)
+    .join("");
+
+  return (
+    DECLARATION +
+    `<Types xmlns="http://schemas.openxmlformats.org/package/2006/content-types">` +
+    `<Default Extension="rels" ContentType="application/vnd.openxmlformats-package.relationships+xml"/>` +
+    `<Default Extension="xml" ContentType="application/xml"/>` +
+    defaults +
+    `<Override PartName="/xl/workbook.xml" ContentType="${CT}.spreadsheetml.sheet.main+xml"/>` +
+    overrides +
+    `<Override PartName="/xl/styles.xml" ContentType="${CT}.spreadsheetml.styles+xml"/>` +
+    `<Override PartName="/xl/sharedStrings.xml" ContentType="${CT}.spreadsheetml.sharedStrings+xml"/>` +
+    drawingOverrides +
+    `<Override PartName="/docProps/core.xml" ContentType="application/vnd.openxmlformats-package.core-properties+xml"/>` +
+    `<Override PartName="/docProps/app.xml" ContentType="${CT}.extended-properties+xml"/>` +
+    `</Types>`
+  );
+};
+
+const ROOT_RELS =
+  DECLARATION +
+  `<Relationships xmlns="${NS_PKG_REL}">` +
+  `<Relationship Id="rId1" Type="${REL}/officeDocument" Target="xl/workbook.xml"/>` +
+  `<Relationship Id="rId2" Type="http://schemas.openxmlformats.org/package/2006/relationships/metadata/core-properties" Target="docProps/core.xml"/>` +
+  `<Relationship Id="rId3" Type="${REL}/extended-properties" Target="docProps/app.xml"/>` +
+  `</Relationships>`;
+
+const APP_XML =
+  DECLARATION +
+  `<Properties xmlns="http://schemas.openxmlformats.org/officeDocument/2006/extended-properties" xmlns:vt="http://schemas.openxmlformats.org/officeDocument/2006/docPropsVTypes"><Application>werkmap</Application></Properties>`;
+
+/** @param {string} name @param {string | undefined} value */
+const tag = (name, value) => (value === undefined ? "" : `<${name}>${esc(value)}</${name}>`);
+
+/**
+ * @param {{ title?: string, creator?: string, subject?: string, description?: string }} meta
+ */
+const coreXml = (meta) =>
+  DECLARATION +
+  `<cp:coreProperties xmlns:cp="http://schemas.openxmlformats.org/package/2006/metadata/core-properties" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:dcterms="http://purl.org/dc/terms/" xmlns:dcmitype="http://purl.org/dc/dcmitype/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">` +
+  tag("dc:title", meta.title) +
+  tag("dc:subject", meta.subject) +
+  tag("dc:creator", meta.creator) +
+  tag("dc:description", meta.description) +
+  `<dcterms:created xsi:type="dcterms:W3CDTF">${CREATED}</dcterms:created>` +
+  `<dcterms:modified xsi:type="dcterms:W3CDTF">${CREATED}</dcterms:modified>` +
+  `</cp:coreProperties>`;
+
+// A sheet reference inside a defined name is always quoted, so a name holding
+// a space or a symbol needs no special case. An apostrophe in the name closes
+// the quote early unless it doubles, and the whole reference is XML-escaped
+// after that like every other name this writer emits.
+/** @param {string} name @param {number} rows */
+const titlesRef = (name, rows) => `${esc(`'${name.replace(/'/g, "''")}'`)}!$1:$${rows}`;
+
+/**
+ * The built-in name that repeats the top rows of a sheet on every printed
+ * page. `localSheetId`, the sheet's 0-based position in `<sheets>`, is what
+ * scopes the name to that worksheet rather than to the whole workbook.
+ *
+ * @param {ReadonlyArray<{ name: string, titles: number }>} sheets
+ */
+const definedNamesXml = (sheets) => {
+  const names = sheets
+    .map((sheet, index) =>
+      sheet.titles === 0
+        ? ""
+        : `<definedName name="_xlnm.Print_Titles" localSheetId="${index}">${titlesRef(sheet.name, sheet.titles)}</definedName>`,
+    )
+    .join("");
+  return names === "" ? "" : `<definedNames>${names}</definedNames>`;
+};
+
+/** @param {ReadonlyArray<{ name: string, titles: number }>} sheets */
+const workbookXml = (sheets) =>
+  DECLARATION +
+  `<workbook xmlns="${NS}" xmlns:r="${NS_R}"><sheets>` +
+  sheets
+    .map(
+      (sheet, index) =>
+        `<sheet name="${esc(sheet.name)}" sheetId="${index + 1}" r:id="rId${index + 1}"/>`,
+    )
+    .join("") +
+  `</sheets>` +
+  definedNamesXml(sheets) +
+  `</workbook>`;
+
+/** @param {number} sheets how many worksheets the workbook holds */
+const workbookRelsXml = (sheets) =>
+  DECLARATION +
+  `<Relationships xmlns="${NS_PKG_REL}">` +
+  Array.from(
+    { length: sheets },
+    (_sheet, index) =>
+      `<Relationship Id="rId${index + 1}" Type="${REL}/worksheet" Target="worksheets/sheet${index + 1}.xml"/>`,
+  ).join("") +
+  `<Relationship Id="rId${sheets + 1}" Type="${REL}/styles" Target="styles.xml"/>` +
+  `<Relationship Id="rId${sheets + 2}" Type="${REL}/sharedStrings" Target="sharedStrings.xml"/>` +
+  `</Relationships>`;
+
+/**
+ * @typedef {(name: string, body: string | Uint8Array, store?: boolean) => void} Part
+ * @typedef {{ sheet: ReturnType<typeof worksheet>, index: number }} Drawing
+ */
+
+/**
+ * Every worksheet part, and the relationship part of each sheet that carries
+ * a drawing.
+ * @param {Part} part
+ * @param {ReadonlyArray<ReturnType<typeof worksheet>>} sheets
+ * @param {ReadonlyArray<Drawing>} drawings
+ */
+const sheetParts = (part, sheets, drawings) => {
+  for (const [index, sheet] of sheets.entries()) {
+    const at = drawings.findIndex((each) => each.index === index);
+    part(`xl/worksheets/sheet${index + 1}.xml`, sheet.xml(at === -1 ? null : 1));
+    if (at !== -1)
+      part(
+        `xl/worksheets/_rels/sheet${index + 1}.xml.rels`,
+        DECLARATION +
+          `<Relationships xmlns="${NS_PKG_REL}"><Relationship Id="rId1" Type="${REL}/drawing" Target="../drawings/drawing${at + 1}.xml"/></Relationships>`,
+      );
+  }
+};
+
+/**
+ * Each drawing part and its relationships. A drawing numbers its own
+ * relationships from one, in the order its pictures were placed, so they line
+ * up with its own part rather than with the workbook-wide media list.
+ * @param {Part} part
+ * @param {ReadonlyArray<Drawing>} drawings
+ * @param {ReadonlyArray<{ format: string }>} media
+ */
+const drawingParts = (part, drawings, media) => {
+  for (const [at, each] of drawings.entries()) {
+    const used = [...new Set(each.sheet.pictures.map((picture) => picture.id))];
+    part(
+      `xl/drawings/drawing${at + 1}.xml`,
+      drawingXml(
+        each.sheet.pictures,
+        each.sheet.pictures.map((picture) => used.indexOf(picture.id)),
+      ),
+    );
+    part(
+      `xl/drawings/_rels/drawing${at + 1}.xml.rels`,
+      DECLARATION +
+        `<Relationships xmlns="${NS_PKG_REL}">` +
+        used
+          .map(
+            (id, index) =>
+              `<Relationship Id="rId${index + 1}" Type="${REL}/image" Target="../media/image${id + 1}.${media[id].format}"/>`,
+          )
+          .join("") +
+        `</Relationships>`,
+    );
+  }
+};
+
 /**
  * Open a workbook.
  *
  * @param {{ title?: string, creator?: string, subject?: string, description?: string }} [meta]
  */
 export const workbook = (meta = {}) => {
-  if (meta === null || typeof meta !== "object")
-    throw TypeError(`workbook: expected a metadata object, got ${JSON.stringify(meta)}`);
+  requireRecord(meta, "workbook", "a metadata object");
 
   const styles = stylesheet();
   const sst = strings();
@@ -972,10 +1425,18 @@ export const workbook = (meta = {}) => {
     return value;
   };
 
-  const title = property("title");
-  const creator = property("creator");
-  const subject = property("subject");
-  const description = property("description");
+  const properties = {
+    title: property("title"),
+    creator: property("creator"),
+    subject: property("subject"),
+    description: property("description"),
+  };
+
+  /** @param {unknown} id */
+  const knows = (id) =>
+    Number.isInteger(id) &&
+    /** @type {number} */ (id) >= 0 &&
+    /** @type {number} */ (id) < media.length;
 
   return {
     /**
@@ -989,30 +1450,22 @@ export const workbook = (meta = {}) => {
         throw TypeError(`image: expected png or jpeg, got ${JSON.stringify(format)}`);
       // Identical bytes deduplicate: a caller embedding the same logo on every
       // sheet pays for it once, and does so without keeping a tally of its own.
-      for (let at = 0; at < media.length; at++)
-        if (media[at].format === format && same(media[at].bytes, bytes)) return at;
+      const seen = media.findIndex((each) => each.format === format && same(each.bytes, bytes));
+      if (seen !== -1) return seen;
       media.push({ bytes, format });
       return media.length - 1;
     },
 
     /** @param {string} name */
     sheet(name) {
-      if (typeof name !== "string" || name === "")
-        throw RangeError(`sheet: expected a name, got ${JSON.stringify(name)}`);
-      if (name.length > NAME_LIMIT)
-        throw RangeError(`sheet: a name is at most ${NAME_LIMIT} characters, got ${name.length}`);
+      requireSheetName(name);
       if (FORBIDDEN_IN_NAME.test(name))
         throw RangeError(
           `sheet: a name cannot contain : \\ / ? * [ ], got ${JSON.stringify(name)}`,
         );
       if (sheets.some((each) => each.name === name))
         throw RangeError(`sheet: a sheet named ${JSON.stringify(name)} already exists`);
-      const made = worksheet(
-        name,
-        styles,
-        sst,
-        (id) => typeof id === "number" && Number.isInteger(id) && id >= 0 && id < media.length,
-      );
+      const made = worksheet(name, styles, sst, knows);
       sheets.push(made);
       return made;
     },
@@ -1022,11 +1475,7 @@ export const workbook = (meta = {}) => {
 
       /** @type {Array<{ name: string, body: Uint8Array, store?: boolean }>} */
       const entries = [];
-      /**
-       * @param {string} name
-       * @param {string | Uint8Array} body
-       * @param {boolean} [store]
-       */
+      /** @type {Part} */
       const part = (name, body, store) =>
         entries.push({
           name,
@@ -1034,144 +1483,22 @@ export const workbook = (meta = {}) => {
           store,
         });
 
-      // Which media each sheet's drawing references, and in what order, so a
-      // drawing's relationship ids line up with its own part rather than with
-      // the workbook-wide media list.
+      // The sheets that carry a drawing part, in sheet order: drawing parts
+      // are numbered by this list, not by sheet index.
       const drawings = sheets
         .map((sheet, index) => ({ sheet, index }))
         .filter((each) => each.sheet.pictures.length > 0);
 
-      const overrides = sheets
-        .map(
-          (_sheet, index) =>
-            `<Override PartName="/xl/worksheets/sheet${index + 1}.xml" ContentType="${CT}.spreadsheetml.worksheet+xml"/>`,
-        )
-        .join("");
-      const drawingOverrides = drawings
-        .map(
-          (_each, at) =>
-            `<Override PartName="/xl/drawings/drawing${at + 1}.xml" ContentType="${CT}.drawing+xml"/>`,
-        )
-        .join("");
-      const defaults = [...new Set(media.map((each) => each.format))]
-        .map((format) => `<Default Extension="${format}" ContentType="${FORMATS.get(format)}"/>`)
-        .join("");
-
-      part(
-        "[Content_Types].xml",
-        DECLARATION +
-          `<Types xmlns="http://schemas.openxmlformats.org/package/2006/content-types">` +
-          `<Default Extension="rels" ContentType="application/vnd.openxmlformats-package.relationships+xml"/>` +
-          `<Default Extension="xml" ContentType="application/xml"/>` +
-          defaults +
-          `<Override PartName="/xl/workbook.xml" ContentType="${CT}.spreadsheetml.sheet.main+xml"/>` +
-          overrides +
-          `<Override PartName="/xl/styles.xml" ContentType="${CT}.spreadsheetml.styles+xml"/>` +
-          `<Override PartName="/xl/sharedStrings.xml" ContentType="${CT}.spreadsheetml.sharedStrings+xml"/>` +
-          drawingOverrides +
-          `<Override PartName="/docProps/core.xml" ContentType="application/vnd.openxmlformats-package.core-properties+xml"/>` +
-          `<Override PartName="/docProps/app.xml" ContentType="${CT}.extended-properties+xml"/>` +
-          `</Types>`,
-      );
-
-      part(
-        "_rels/.rels",
-        DECLARATION +
-          `<Relationships xmlns="${NS_PKG_REL}">` +
-          `<Relationship Id="rId1" Type="${REL}/officeDocument" Target="xl/workbook.xml"/>` +
-          `<Relationship Id="rId2" Type="http://schemas.openxmlformats.org/package/2006/relationships/metadata/core-properties" Target="docProps/core.xml"/>` +
-          `<Relationship Id="rId3" Type="${REL}/extended-properties" Target="docProps/app.xml"/>` +
-          `</Relationships>`,
-      );
-
-      /** @param {string} name @param {string | undefined} value */
-      const tag = (name, value) => (value === undefined ? "" : `<${name}>${esc(value)}</${name}>`);
-      part(
-        "docProps/core.xml",
-        DECLARATION +
-          `<cp:coreProperties xmlns:cp="http://schemas.openxmlformats.org/package/2006/metadata/core-properties" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:dcterms="http://purl.org/dc/terms/" xmlns:dcmitype="http://purl.org/dc/dcmitype/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">` +
-          tag("dc:title", title) +
-          tag("dc:subject", subject) +
-          tag("dc:creator", creator) +
-          tag("dc:description", description) +
-          `<dcterms:created xsi:type="dcterms:W3CDTF">${CREATED}</dcterms:created>` +
-          `<dcterms:modified xsi:type="dcterms:W3CDTF">${CREATED}</dcterms:modified>` +
-          `</cp:coreProperties>`,
-      );
-
-      part(
-        "docProps/app.xml",
-        DECLARATION +
-          `<Properties xmlns="http://schemas.openxmlformats.org/officeDocument/2006/extended-properties" xmlns:vt="http://schemas.openxmlformats.org/officeDocument/2006/docPropsVTypes"><Application>werkmap</Application></Properties>`,
-      );
-
-      part(
-        "xl/workbook.xml",
-        DECLARATION +
-          `<workbook xmlns="${NS}" xmlns:r="${NS_R}"><sheets>` +
-          sheets
-            .map(
-              (sheet, index) =>
-                `<sheet name="${esc(sheet.name)}" sheetId="${index + 1}" r:id="rId${index + 1}"/>`,
-            )
-            .join("") +
-          `</sheets></workbook>`,
-      );
-
-      part(
-        "xl/_rels/workbook.xml.rels",
-        DECLARATION +
-          `<Relationships xmlns="${NS_PKG_REL}">` +
-          sheets
-            .map(
-              (_sheet, index) =>
-                `<Relationship Id="rId${index + 1}" Type="${REL}/worksheet" Target="worksheets/sheet${index + 1}.xml"/>`,
-            )
-            .join("") +
-          `<Relationship Id="rId${sheets.length + 1}" Type="${REL}/styles" Target="styles.xml"/>` +
-          `<Relationship Id="rId${sheets.length + 2}" Type="${REL}/sharedStrings" Target="sharedStrings.xml"/>` +
-          `</Relationships>`,
-      );
-
-      for (const [index, sheet] of sheets.entries()) {
-        const at = drawings.findIndex((each) => each.index === index);
-        part(`xl/worksheets/sheet${index + 1}.xml`, sheet.xml(at === -1 ? null : 1));
-        if (at !== -1)
-          part(
-            `xl/worksheets/_rels/sheet${index + 1}.xml.rels`,
-            DECLARATION +
-              `<Relationships xmlns="${NS_PKG_REL}"><Relationship Id="rId1" Type="${REL}/drawing" Target="../drawings/drawing${at + 1}.xml"/></Relationships>`,
-          );
-      }
-
+      part("[Content_Types].xml", contentTypesXml(sheets.length, drawings.length, media));
+      part("_rels/.rels", ROOT_RELS);
+      part("docProps/core.xml", coreXml(properties));
+      part("docProps/app.xml", APP_XML);
+      part("xl/workbook.xml", workbookXml(sheets));
+      part("xl/_rels/workbook.xml.rels", workbookRelsXml(sheets.length));
+      sheetParts(part, sheets, drawings);
       part("xl/styles.xml", styles.xml());
       part("xl/sharedStrings.xml", sst.xml());
-
-      for (const [at, each] of drawings.entries()) {
-        // Each drawing numbers its own relationships from one, in the order
-        // its pictures were placed.
-        const used = [...new Set(each.sheet.pictures.map((picture) => picture.id))];
-        part(
-          `xl/drawings/drawing${at + 1}.xml`,
-          drawingXml(
-            each.sheet.pictures,
-            each.sheet.pictures.map((picture) => used.indexOf(picture.id)),
-          ),
-        );
-        part(
-          `xl/drawings/_rels/drawing${at + 1}.xml.rels`,
-          DECLARATION +
-            `<Relationships xmlns="${NS_PKG_REL}">` +
-            used
-              .map(
-                (id, index) =>
-                  `<Relationship Id="rId${index + 1}" Type="${REL}/image" Target="../media/image${id + 1}.${media[id].format}"/>`,
-              )
-              .join("") +
-            `</Relationships>`,
-        );
-      }
-
+      drawingParts(part, drawings, media);
       for (const [index, each] of media.entries())
         part(`xl/media/image${index + 1}.${each.format}`, each.bytes, true);