@bongos/core 1.19.1061 → 1.19.1062

package/modules/copy-desk/docx.js

@@ -0,0 +1,818 @@
+// modules/copy-desk/docx.js — the Word round trip for a page tweak (task 1004320 /
+// BV2.TW09, ADR 0341 D12): download a page's words as a .docx, work offline, and
+// upload the file back into the draft.
+//
+// NO DEPENDENCY. A .docx is a zip of XML parts, so this file carries a small zip
+// writer and reader on node:zlib and a small XML reader, and nothing else. The
+// spec rules out a paid service and ADR 0341 rejects a heavy library: the format
+// is simple enough, and every byte of an upload is someone else's input, so a
+// reader we can bound is worth more than a general one we cannot.
+//
+// PURE OVER BUFFERS: no fs, no DB, no network. The one require is node:zlib.
+// copy_no_cms.mjs pins that, because this file handles an artist's wording.
+//
+// THE FILE (ADR 0341 D12):
+//   * the page title as the Title, and each run of lines in one section as a
+//     Heading 2 (a section that recurs later on the page gets a heading again);
+//   * one paragraph per line in page order, showing the draft's `after` (or the
+//     page's current text), inside a plain-text content control (w:sdt) whose
+//     tag is the line key. The control is RUN-level, inside the paragraph, which
+//     is the shape Word itself makes for a plain-text control and the one that
+//     stops Enter from splitting a line;
+//   * shared and unplaced lines in their own paragraph style, with a Word
+//     comment ("changes this on every page", "goes to an engineer");
+//   * page_id and reading_hash as custom document properties;
+//   * the text each line was SHOWN with, in a custom XML part. That part is
+//     what makes the upload a merge rather than a replace: a line is taken from
+//     the file only when the artist changed it in Word, so a line they rewrote
+//     in the studio after downloading keeps that rewrite.
+//
+// THE UPLOAD maps paragraphs back to lines by tag, or by position when every tag
+// is gone, and refuses by name: structure_changed (a line added, dropped or
+// reordered, or a heading changed), wrong_page, reading_moved. Word's own habits
+// are read the way Word writes them: one line's text split across many runs,
+// proofing marks, tracked insertions (the upload reads the document with its
+// tracked changes accepted), and smart quotes (see foldQuotes).
+
+'use strict';
+
+const zlib = require('node:zlib');
+
+// ---------------------------------------------------------------------------
+// Limits. An upload is user-supplied input: every size is capped before it is
+// read, and nothing is inflated past its cap (a zip bomb stops at the cap).
+// ---------------------------------------------------------------------------
+
+// The file itself. A text-only page file is tens of kilobytes; 5 MB leaves room
+// for an artist who pasted a picture into it and still bounds the request.
+const MAX_UPLOAD_BYTES = 5 * 1024 * 1024;
+// One inflated part. The longest page (under 500 lines) makes a document part
+// well under 1 MB.
+const MAX_PART_BYTES = 8 * 1024 * 1024;
+const MAX_ZIP_ENTRIES = 2000;
+const MAX_XML_DEPTH = 256;
+const MAX_BASELINE_PARTS = 20;
+
+const DOCX_MIME = 'application/vnd.openxmlformats-officedocument.wordprocessingml.document';
+
+const NS = Object.freeze({
+  w: 'http://schemas.openxmlformats.org/wordprocessingml/2006/main',
+  wStrict: 'http://purl.oclc.org/ooxml/wordprocessingml/main',
+  mc: 'http://schemas.openxmlformats.org/markup-compatibility/2006',
+  rels: 'http://schemas.openxmlformats.org/package/2006/relationships',
+  custom: 'http://schemas.openxmlformats.org/officeDocument/2006/custom-properties',
+  vt: 'http://schemas.openxmlformats.org/officeDocument/2006/docPropsVTypes',
+  baseline: 'urn:cloud-bongos:page-tweak:shown:1',
+});
+const REL = Object.freeze({
+  officeDocument: 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/officeDocument',
+  customProps: 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/custom-properties',
+});
+
+// The paragraph styles this file writes, and reads back.
+const STYLE = Object.freeze({
+  title: 'Title',
+  heading: 'Heading2',
+  note: 'TweakNote',
+  shared: 'TweakShared',
+  unplaced: 'TweakUnplaced',
+});
+// The margin notes the editor shows beside these lines (Editor.dc.html).
+const COMMENT_TEXT = Object.freeze({
+  shared: 'changes this on every page',
+  unplaced: 'goes to an engineer',
+});
+const NOTE_TEXT = 'Rewrite any line where it stands, then upload this file back into the editor. '
+  + 'Keep one paragraph per line: a paragraph added, removed or moved is refused. '
+  + 'Keep each {…} as it is: the page fills in a value there.';
+
+const LINE_KEY_RE = /^L[0-9]{4,}$/;
+
+function fail(code, detail) { return { ok: false, code, detail: detail || {} }; }
+
+// ---------------------------------------------------------------------------
+// ZIP: a writer (deflate, deterministic: fixed timestamps, given order) and a
+// bounded reader (stored or deflate; no zip64, no encryption).
+// ---------------------------------------------------------------------------
+
+const CRC_TABLE = (() => {
+  const t = new Int32Array(256);
+  for (let n = 0; n < 256; n++) {
+    let c = n;
+    for (let k = 0; k < 8; k++) c = (c & 1) ? (0xEDB88320 ^ (c >>> 1)) : (c >>> 1);
+    t[n] = c;
+  }
+  return t;
+})();
+
+function crc32(buf) {
+  let c = -1;
+  for (let i = 0; i < buf.length; i++) c = CRC_TABLE[(c ^ buf[i]) & 0xFF] ^ (c >>> 8);
+  return (c ^ -1) >>> 0;
+}
+
+// 1980-01-01 00:00, the zip epoch: the same page makes the same bytes.
+const DOS_TIME = 0;
+const DOS_DATE = (1 << 5) | 1;
+const UTF8_NAMES = 0x0800;
+
+// writeZip([{ name, data }]) -> Buffer
+function writeZip(entries) {
+  const locals = [];
+  const centrals = [];
+  let offset = 0;
+  for (const e of entries) {
+    const name = Buffer.from(e.name, 'utf8');
+    const data = Buffer.isBuffer(e.data) ? e.data : Buffer.from(String(e.data), 'utf8');
+    const packed = zlib.deflateRawSync(data);
+    const crc = crc32(data);
+    const local = Buffer.alloc(30);
+    local.writeUInt32LE(0x04034b50, 0);
+    local.writeUInt16LE(20, 4);
+    local.writeUInt16LE(UTF8_NAMES, 6);
+    local.writeUInt16LE(8, 8);
+    local.writeUInt16LE(DOS_TIME, 10);
+    local.writeUInt16LE(DOS_DATE, 12);
+    local.writeUInt32LE(crc, 14);
+    local.writeUInt32LE(packed.length, 18);
+    local.writeUInt32LE(data.length, 22);
+    local.writeUInt16LE(name.length, 26);
+    local.writeUInt16LE(0, 28);
+    const central = Buffer.alloc(46);
+    central.writeUInt32LE(0x02014b50, 0);
+    central.writeUInt16LE(20, 4);
+    central.writeUInt16LE(20, 6);
+    central.writeUInt16LE(UTF8_NAMES, 8);
+    central.writeUInt16LE(8, 10);
+    central.writeUInt16LE(DOS_TIME, 12);
+    central.writeUInt16LE(DOS_DATE, 14);
+    central.writeUInt32LE(crc, 16);
+    central.writeUInt32LE(packed.length, 20);
+    central.writeUInt32LE(data.length, 24);
+    central.writeUInt16LE(name.length, 28);
+    central.writeUInt32LE(offset, 42);
+    locals.push(local, name, packed);
+    centrals.push(central, name);
+    offset += local.length + name.length + packed.length;
+  }
+  const cd = Buffer.concat(centrals);
+  const end = Buffer.alloc(22);
+  end.writeUInt32LE(0x06054b50, 0);
+  end.writeUInt16LE(entries.length, 8);
+  end.writeUInt16LE(entries.length, 10);
+  end.writeUInt32LE(cd.length, 12);
+  end.writeUInt32LE(offset, 16);
+  return Buffer.concat([...locals, cd, end]);
+}
+
+function isZip(buf) {
+  return Buffer.isBuffer(buf) && buf.length >= 4 && buf.readUInt32LE(0) === 0x04034b50;
+}
+
+// readZip(buf, { want }) -> { ok, names, parts: Map(name -> Buffer) } | refusal
+//
+// Reads the central directory, then inflates ONLY the entries `want(name)`
+// accepts, each capped at MAX_PART_BYTES. Sizes and offsets come from the
+// central directory (Word writes data descriptors, so a local header's sizes can
+// be zero). Every bound is checked before a byte is read.
+function readZip(buf, { want = () => true, maxPartBytes = MAX_PART_BYTES } = {}) {
+  const bad = (reason) => fail('not_a_docx', { reason });
+  if (!isZip(buf)) return bad('not a zip file');
+  const min = Math.max(0, buf.length - 22 - 0xFFFF);
+  let eocd = -1;
+  for (let i = buf.length - 22; i >= min; i--) {
+    if (buf.readUInt32LE(i) === 0x06054b50) { eocd = i; break; }
+  }
+  if (eocd < 0) return bad('the zip has no directory (truncated?)');
+  const count = buf.readUInt16LE(eocd + 10);
+  const cdSize = buf.readUInt32LE(eocd + 12);
+  const cdOffset = buf.readUInt32LE(eocd + 16);
+  if (count === 0xFFFF || cdSize === 0xFFFFFFFF || cdOffset === 0xFFFFFFFF) return bad('zip64 is not read here');
+  if (count > MAX_ZIP_ENTRIES) return bad(`more than ${MAX_ZIP_ENTRIES} entries`);
+  if (cdOffset + cdSize > eocd) return bad('the zip directory is out of bounds');
+
+  const names = [];
+  const parts = new Map();
+  let p = cdOffset;
+  for (let n = 0; n < count; n++) {
+    if (p + 46 > eocd || buf.readUInt32LE(p) !== 0x02014b50) return bad('a zip directory entry is corrupt');
+    const flags = buf.readUInt16LE(p + 8);
+    const method = buf.readUInt16LE(p + 10);
+    const crc = buf.readUInt32LE(p + 16);
+    const csize = buf.readUInt32LE(p + 20);
+    const usize = buf.readUInt32LE(p + 24);
+    const nlen = buf.readUInt16LE(p + 28);
+    const elen = buf.readUInt16LE(p + 30);
+    const clen = buf.readUInt16LE(p + 32);
+    const lho = buf.readUInt32LE(p + 42);
+    if (p + 46 + nlen > eocd) return bad('a zip entry name is out of bounds');
+    const name = buf.toString('utf8', p + 46, p + 46 + nlen).replace(/\\/g, '/').replace(/^\/+/, '');
+    p += 46 + nlen + elen + clen;
+    names.push(name);
+    if (!want(name)) continue;
+    if (parts.has(name)) return bad(`the zip holds ${name} twice`);
+    if (flags & 1) return bad('the file is encrypted');
+    if (usize > maxPartBytes) return fail('upload_too_large', { part: name, max_bytes: maxPartBytes });
+    if (lho + 30 > buf.length || buf.readUInt32LE(lho) !== 0x04034b50) return bad(`the entry ${name} is corrupt`);
+    const start = lho + 30 + buf.readUInt16LE(lho + 26) + buf.readUInt16LE(lho + 28);
+    if (start + csize > buf.length) return bad(`the entry ${name} is out of bounds`);
+    const raw = buf.subarray(start, start + csize);
+    let data;
+    if (method === 0) {
+      data = Buffer.from(raw);
+    } else if (method === 8) {
+      try {
+        data = zlib.inflateRawSync(raw, { maxOutputLength: maxPartBytes });
+      } catch (err) {
+        if (err && (err.code === 'ERR_BUFFER_TOO_LARGE' || err instanceof RangeError)) {
+          return fail('upload_too_large', { part: name, max_bytes: maxPartBytes });
+        }
+        return bad(`the entry ${name} does not inflate`);
+      }
+    } else {
+      return bad(`the entry ${name} uses compression method ${method}`);
+    }
+    if (data.length !== usize || crc32(data) !== crc) return bad(`the entry ${name} is corrupt`);
+    parts.set(name, data);
+  }
+  return { ok: true, names, parts };
+}
+
+// ---------------------------------------------------------------------------
+// XML. A small, namespace-aware reader into a light tree, and escaping for the
+// writer. It never resolves an entity beyond the five predefined ones and
+// character references, and refuses a DOCTYPE, so no entity can expand.
+// ---------------------------------------------------------------------------
+
+function escapeXml(s) {
+  return String(s).replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&apos;' }[c]))
+    // A character XML 1.0 cannot carry at all (control characters) is dropped.
+    .replace(/[\u0000-\u0008\u000B\u000C\u000E-\u001F\uFFFE\uFFFF]/g, '');
+}
+
+const NAMED_ENTITIES = { lt: '<', gt: '>', amp: '&', quot: '"', apos: "'" };
+function decodeEntities(s) {
+  return s.replace(/&(#x[0-9a-fA-F]+|#[0-9]+|[a-zA-Z]+);/g, (m, e) => {
+    if (e[0] === '#') {
+      const code = e[1] === 'x' || e[1] === 'X' ? parseInt(e.slice(2), 16) : parseInt(e.slice(1), 10);
+      return Number.isFinite(code) && code >= 0 && code <= 0x10FFFF ? String.fromCodePoint(code) : m;
+    }
+    return Object.prototype.hasOwnProperty.call(NAMED_ENTITIES, e) ? NAMED_ENTITIES[e] : m;
+  });
+}
+
+const ATTR_RE = /([^\s=/>]+)\s*=\s*(?:"([^"]*)"|'([^']*)')/g;
+
+// parseXml(text) -> root element { name, local, ns, attrs, scope, children }
+// Children are elements or strings. Throws on malformed input; the callers
+// catch it and answer not_a_docx.
+function parseXml(text) {
+  const src = String(text).replace(/^\uFEFF/, '');
+  const root = { name: '#root', local: '#root', ns: null, attrs: {}, scope: { xml: 'http://www.w3.org/XML/1998/namespace' }, children: [] };
+  const stack = [root];
+  let i = 0;
+  while (i < src.length) {
+    const lt = src.indexOf('<', i);
+    if (lt < 0) { pushText(stack, src.slice(i)); break; }
+    if (lt > i) pushText(stack, src.slice(i, lt));
+    if (src.startsWith('<!--', lt)) {
+      const end = src.indexOf('-->', lt + 4);
+      if (end < 0) throw new Error('unterminated comment');
+      i = end + 3;
+    } else if (src.startsWith('<?', lt)) {
+      const end = src.indexOf('?>', lt + 2);
+      if (end < 0) throw new Error('unterminated processing instruction');
+      i = end + 2;
+    } else if (src.startsWith('<![CDATA[', lt)) {
+      const end = src.indexOf(']]>', lt + 9);
+      if (end < 0) throw new Error('unterminated CDATA');
+      stack[stack.length - 1].children.push(src.slice(lt + 9, end));
+      i = end + 3;
+    } else if (src.startsWith('<!', lt)) {
+      throw new Error('a DOCTYPE or declaration is not read here');
+    } else if (src[lt + 1] === '/') {
+      const end = src.indexOf('>', lt);
+      if (end < 0) throw new Error('unterminated end tag');
+      const name = src.slice(lt + 2, end).trim();
+      const top = stack.pop();
+      if (!top || top.name !== name || !stack.length) throw new Error(`mismatched end tag ${name}`);
+      i = end + 1;
+    } else {
+      // Find the tag's end, stepping over quoted attribute values.
+      let j = lt + 1;
+      let quote = null;
+      for (; j < src.length; j++) {
+        const c = src[j];
+        if (quote) { if (c === quote) quote = null; } else if (c === '"' || c === "'") quote = c; else if (c === '>') break;
+      }
+      if (j >= src.length) throw new Error('unterminated tag');
+      let body = src.slice(lt + 1, j);
+      const selfClosing = body.endsWith('/');
+      if (selfClosing) body = body.slice(0, -1);
+      const m = /^([^\s/>]+)/.exec(body);
+      if (!m) throw new Error('a tag has no name');
+      const name = m[1];
+      const attrs = {};
+      for (const a of body.slice(name.length).matchAll(ATTR_RE)) attrs[a[1]] = decodeEntities(a[2] != null ? a[2] : a[3]);
+      const parent = stack[stack.length - 1];
+      const scope = { ...parent.scope };
+      for (const [k, v] of Object.entries(attrs)) {
+        if (k === 'xmlns') scope[''] = v;
+        else if (k.startsWith('xmlns:')) scope[k.slice(6)] = v;
+      }
+      const colon = name.indexOf(':');
+      const prefix = colon < 0 ? '' : name.slice(0, colon);
+      const el = { name, local: colon < 0 ? name : name.slice(colon + 1), ns: scope[prefix] || null, attrs, scope, children: [] };
+      parent.children.push(el);
+      if (!selfClosing) {
+        if (stack.length > MAX_XML_DEPTH) throw new Error('the XML is nested too deeply');
+        stack.push(el);
+      }
+      i = j + 1;
+    }
+  }
+  if (stack.length !== 1) throw new Error('unclosed element');
+  const top = root.children.find((c) => typeof c !== 'string');
+  if (!top) throw new Error('no root element');
+  return top;
+}
+
+function pushText(stack, raw) {
+  stack[stack.length - 1].children.push(decodeEntities(raw));
+}
+
+const isW = (el) => el && typeof el !== 'string' && (el.ns === NS.w || el.ns === NS.wStrict);
+const isWEl = (el, local) => isW(el) && el.local === local;
+const kids = (el) => (el.children || []).filter((c) => typeof c !== 'string');
+
+// An attribute by namespace and local name (w:val), resolved through the scope.
+function attrNs(el, ns, local) {
+  for (const [k, v] of Object.entries(el.attrs || {})) {
+    const colon = k.indexOf(':');
+    if (colon < 0) continue;
+    if (k.slice(colon + 1) === local && (el.scope[k.slice(0, colon)] === ns || (ns === NS.w && el.scope[k.slice(0, colon)] === NS.wStrict))) return v;
+  }
+  return null;
+}
+const wVal = (el) => (el ? attrNs(el, NS.w, 'val') : null);
+const firstW = (el, local) => (el ? kids(el).find((c) => isWEl(c, local)) || null : null);
+
+function textOf(el) {
+  return (el.children || []).map((c) => (typeof c === 'string' ? c : textOf(c))).join('');
+}
+
+// ---------------------------------------------------------------------------
+// The download.
+// ---------------------------------------------------------------------------
+
+// The lines as the file shows them: the draft's `after` where the draft is on
+// this very reading, else the page's current text. A draft saved on an older
+// reading is not shown: its keys may name other lines now.
+function shownLines(readingPage, draft) {
+  const after = new Map();
+  if (draft && draft.reading_hash === readingPage.reading_hash) {
+    for (const l of draft.lines || []) after.set(l.key, l.after);
+  }
+  return (readingPage.lines || []).map((l) => ({
+    key: l.key,
+    section: l.section == null ? '' : String(l.section),
+    placement: l.placement,
+    text: after.has(l.key) ? after.get(l.key) : l.text,
+  }));
+}
+
+// The consecutive runs of one section, in page order: each run is a heading.
+function sectionRuns(lines) {
+  const runs = [];
+  for (const l of lines) {
+    const section = l.section == null ? '' : String(l.section);
+    const last = runs[runs.length - 1];
+    if (last && last.section === section) last.keys.push(l.key);
+    else runs.push({ section, keys: [l.key] });
+  }
+  return runs;
+}
+
+const XML_HEAD = '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n';
+const W_DECL = `xmlns:w="${NS.w}" xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships"`;
+
+function run(text, rStyle) {
+  const rPr = rStyle ? `<w:rPr><w:rStyle w:val="${rStyle}"/></w:rPr>` : '';
+  return `<w:r>${rPr}<w:t xml:space="preserve">${escapeXml(text)}</w:t></w:r>`;
+}
+function styledPara(style, inner) {
+  return `<w:p><w:pPr><w:pStyle w:val="${style}"/></w:pPr>${inner}</w:p>`;
+}
+
+function documentXml({ title, lines }) {
+  const body = [styledPara(STYLE.title, run(title)), styledPara(STYLE.note, run(NOTE_TEXT))];
+  const comments = [];
+  let current = null;
+  lines.forEach((l, idx) => {
+    if (current === null || l.section !== current) {
+      current = l.section;
+      body.push(styledPara(STYLE.heading, run(l.section)));
+    }
+    const note = COMMENT_TEXT[l.placement];
+    const style = note ? STYLE[l.placement] : null;
+    const sdt = `<w:sdt><w:sdtPr><w:tag w:val="${escapeXml(l.key)}"/><w:id w:val="${idx + 1}"/><w:text/></w:sdtPr>`
+      + `<w:sdtContent>${run(l.text)}</w:sdtContent></w:sdt>`;
+    let inner = sdt;
+    if (note) {
+      const id = comments.length;
+      comments.push(note);
+      inner = `<w:commentRangeStart w:id="${id}"/>${sdt}<w:commentRangeEnd w:id="${id}"/>`
+        + `<w:r><w:rPr><w:rStyle w:val="CommentReference"/></w:rPr><w:commentReference w:id="${id}"/></w:r>`;
+    }
+    body.push(style ? styledPara(style, inner) : `<w:p>${inner}</w:p>`);
+  });
+  const sect = '<w:sectPr><w:pgSz w:w="11906" w:h="16838"/><w:pgMar w:top="1440" w:right="1440" w:bottom="1440" w:left="1440" w:header="708" w:footer="708" w:gutter="0"/></w:sectPr>';
+  return {
+    document: `${XML_HEAD}<w:document ${W_DECL}><w:body>${body.join('')}${sect}</w:body></w:document>`,
+    comments: `${XML_HEAD}<w:comments ${W_DECL}>${comments.map((c, id) => `<w:comment w:id="${id}" w:author="Tweak Mode" w:initials="TM">`
+      + `<w:p><w:pPr><w:pStyle w:val="CommentText"/></w:pPr>${run(c)}</w:p></w:comment>`).join('')}</w:comments>`,
+  };
+}
+
+const STYLES_XML = `${XML_HEAD}<w:styles ${W_DECL}>`
+  + '<w:docDefaults><w:rPrDefault><w:rPr><w:rFonts w:ascii="Calibri" w:hAnsi="Calibri" w:cs="Calibri"/><w:sz w:val="22"/></w:rPr></w:rPrDefault>'
+  + '<w:pPrDefault><w:pPr><w:spacing w:after="120"/></w:pPr></w:pPrDefault></w:docDefaults>'
+  + '<w:style w:type="paragraph" w:default="1" w:styleId="Normal"><w:name w:val="Normal"/></w:style>'
+  + '<w:style w:type="paragraph" w:styleId="Title"><w:name w:val="Title"/><w:basedOn w:val="Normal"/><w:next w:val="Normal"/><w:pPr><w:spacing w:after="240"/></w:pPr><w:rPr><w:sz w:val="48"/></w:rPr></w:style>'
+  + '<w:style w:type="paragraph" w:styleId="Heading2"><w:name w:val="heading 2"/><w:basedOn w:val="Normal"/><w:next w:val="Normal"/><w:pPr><w:keepNext/><w:spacing w:before="240" w:after="80"/><w:outlineLvl w:val="1"/></w:pPr><w:rPr><w:b/><w:sz w:val="28"/></w:rPr></w:style>'
+  + '<w:style w:type="paragraph" w:customStyle="1" w:styleId="TweakNote"><w:name w:val="Tweak note"/><w:basedOn w:val="Normal"/><w:rPr><w:i/><w:color w:val="666666"/><w:sz w:val="20"/></w:rPr></w:style>'
+  + '<w:style w:type="paragraph" w:customStyle="1" w:styleId="TweakShared"><w:name w:val="Tweak shared line"/><w:basedOn w:val="Normal"/><w:rPr><w:color w:val="1F5F99"/></w:rPr></w:style>'
+  + '<w:style w:type="paragraph" w:customStyle="1" w:styleId="TweakUnplaced"><w:name w:val="Tweak engineer line"/><w:basedOn w:val="Normal"/><w:rPr><w:i/><w:color w:val="8A5A00"/></w:rPr></w:style>'
+  + '<w:style w:type="character" w:styleId="CommentReference"><w:name w:val="annotation reference"/><w:rPr><w:sz w:val="16"/></w:rPr></w:style>'
+  + '<w:style w:type="paragraph" w:styleId="CommentText"><w:name w:val="annotation text"/><w:basedOn w:val="Normal"/><w:rPr><w:sz w:val="20"/></w:rPr></w:style>'
+  + '</w:styles>';
+
+function customPropsXml(props) {
+  const items = Object.entries(props).map(([name, value], i) => `<property fmtid="{D5CDD505-2E9C-101B-9397-08002B2CF9AE}" pid="${i + 2}" name="${escapeXml(name)}">`
+    + `<vt:lpwstr>${escapeXml(value)}</vt:lpwstr></property>`);
+  return `${XML_HEAD}<Properties xmlns="${NS.custom}" xmlns:vt="${NS.vt}">${items.join('')}</Properties>`;
+}
+
+function baselineXml(lines) {
+  return `${XML_HEAD}<shown xmlns="${NS.baseline}">${lines.map((l) => `<line key="${escapeXml(l.key)}">${escapeXml(l.text)}</line>`).join('')}</shown>`;
+}
+
+// A GUID for the custom XML part, derived from the page so the same download
+// makes the same bytes.
+function guidFor(seed) {
+  const h = [0, 1, 2, 3].map((i) => crc32(Buffer.from(`${i}:${seed}`)).toString(16).padStart(8, '0')).join('').toUpperCase();
+  return `{${h.slice(0, 8)}-${h.slice(8, 12)}-${h.slice(12, 16)}-${h.slice(16, 20)}-${h.slice(20, 32)}}`;
+}
+
+// composeDownload({ readingPage, title, draft }) -> Buffer (the .docx)
+function composeDownload({ readingPage, title, draft }) {
+  const lines = shownLines(readingPage, draft);
+  const pageTitle = String(title || readingPage.title || readingPage.id);
+  const doc = documentXml({ title: pageTitle, lines });
+  const rels = (items) => `${XML_HEAD}<Relationships xmlns="${NS.rels}">${items.map(([id, type, target]) => `<Relationship Id="${id}" Type="${type}" Target="${target}"/>`).join('')}</Relationships>`;
+  const OD = 'http://schemas.openxmlformats.org/officeDocument/2006/relationships';
+  return writeZip([
+    { name: '[Content_Types].xml', data: `${XML_HEAD}<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"/>'
+      + '<Override PartName="/word/document.xml" ContentType="application/vnd.openxmlformats-officedocument.wordprocessingml.document.main+xml"/>'
+      + '<Override PartName="/word/styles.xml" ContentType="application/vnd.openxmlformats-officedocument.wordprocessingml.styles+xml"/>'
+      + '<Override PartName="/word/comments.xml" ContentType="application/vnd.openxmlformats-officedocument.wordprocessingml.comments+xml"/>'
+      + '<Override PartName="/docProps/core.xml" ContentType="application/vnd.openxmlformats-package.core-properties+xml"/>'
+      + '<Override PartName="/docProps/custom.xml" ContentType="application/vnd.openxmlformats-officedocument.custom-properties+xml"/>'
+      + '<Override PartName="/customXml/itemProps1.xml" ContentType="application/vnd.openxmlformats-officedocument.customXmlProperties+xml"/>'
+      + '</Types>' },
+    { name: '_rels/.rels', data: rels([
+      ['rId1', REL.officeDocument, 'word/document.xml'],
+      ['rId2', 'http://schemas.openxmlformats.org/package/2006/relationships/metadata/core-properties', 'docProps/core.xml'],
+      ['rId3', REL.customProps, 'docProps/custom.xml'],
+    ]) },
+    { name: 'word/document.xml', data: doc.document },
+    { name: 'word/_rels/document.xml.rels', data: rels([
+      ['rId1', `${OD}/styles`, 'styles.xml'],
+      ['rId2', `${OD}/comments`, 'comments.xml'],
+      ['rId3', `${OD}/customXml`, '../customXml/item1.xml'],
+    ]) },
+    { name: 'word/styles.xml', data: STYLES_XML },
+    { name: 'word/comments.xml', data: doc.comments },
+    { name: 'docProps/core.xml', data: `${XML_HEAD}<cp:coreProperties xmlns:cp="http://schemas.openxmlformats.org/package/2006/metadata/core-properties" xmlns:dc="http://purl.org/dc/elements/1.1/">`
+      + `<dc:title>${escapeXml(`Tweak: ${pageTitle}`)}</dc:title></cp:coreProperties>` },
+    { name: 'docProps/custom.xml', data: customPropsXml({ page_id: readingPage.id, reading_hash: readingPage.reading_hash || '' }) },
+    { name: 'customXml/item1.xml', data: baselineXml(lines) },
+    { name: 'customXml/itemProps1.xml', data: `${XML_HEAD}<ds:datastoreItem ds:itemID="${guidFor(`${readingPage.id}/${readingPage.reading_hash}`)}" xmlns:ds="http://schemas.openxmlformats.org/officeDocument/2006/customXml"><ds:schemaRefs/></ds:datastoreItem>` },
+    { name: 'customXml/_rels/item1.xml.rels', data: rels([['rId1', `${OD}/customXmlProps`, 'itemProps1.xml']]) },
+  ]);
+}
+
+// The download's file name: the page id, with the colon a file system refuses.
+function downloadName(pageId) {
+  return `tweak-${String(pageId).replace(/[^a-z0-9-]+/gi, '-')}.docx`;
+}
+
+// ---------------------------------------------------------------------------
+// The upload: read the file.
+// ---------------------------------------------------------------------------
+
+function relTarget(relsXml, type) {
+  if (!relsXml) return null;
+  const root = parseXml(relsXml);
+  const rel = kids(root).find((r) => r.local === 'Relationship' && r.attrs.Type === type);
+  return rel ? String(rel.attrs.Target || '').replace(/^\/+/, '') : null;
+}
+
+function readCustomProps(xml) {
+  const out = {};
+  if (!xml) return out;
+  const root = parseXml(xml);
+  for (const prop of kids(root).filter((c) => c.local === 'property')) {
+    const name = prop.attrs.name;
+    const value = kids(prop)[0];
+    if (name && value) out[name] = textOf(value);
+  }
+  return out;
+}
+
+function readBaseline(xml) {
+  const root = parseXml(xml);
+  if (root.ns !== NS.baseline || root.local !== 'shown') return null;
+  const out = new Map();
+  for (const l of kids(root).filter((c) => c.local === 'line')) {
+    if (typeof l.attrs.key === 'string' && !out.has(l.attrs.key)) out.set(l.attrs.key, textOf(l));
+  }
+  return out;
+}
+
+// A paragraph's visible text, as Word stores it: every w:t in every run, in
+// order, however many runs one sentence was split into. Tracked insertions
+// count and tracked deletions do not (w:delText is skipped, and w:del and
+// w:moveFrom are skipped whole), so the text is the document with its changes
+// accepted. Field instructions, run and paragraph properties and the Fallback
+// copy of alternate content are not text.
+const SKIP_SUBTREES = new Set(['pPr', 'rPr', 'del', 'moveFrom', 'instrText', 'delText', 'delInstrText', 'sdtPr', 'sdtEndPr', 'footnoteReference', 'endnoteReference']);
+function paragraphText(p) {
+  let out = '';
+  const walk = (el) => {
+    for (const c of el.children || []) {
+      if (typeof c === 'string') continue;
+      if (c.ns === NS.mc && c.local === 'Fallback') continue;
+      if (isW(c)) {
+        if (SKIP_SUBTREES.has(c.local)) continue;
+        if (c.local === 't') { out += textOf(c); continue; }
+        if (c.local === 'tab' || c.local === 'br' || c.local === 'cr') { out += ' '; continue; }
+        if (c.local === 'noBreakHyphen') { out += '-'; continue; }
+      }
+      walk(c);
+    }
+  };
+  walk(p);
+  return out;
+}
+
+// The line tags inside a paragraph: its run-level content controls.
+function inlineTags(p) {
+  const tags = [];
+  const walk = (el) => {
+    for (const c of kids(el)) {
+      if (isWEl(c, 'sdt')) {
+        const tag = wVal(firstW(firstW(c, 'sdtPr'), 'tag'));
+        if (tag != null) tags.push(tag);
+      }
+      if (!(isW(c) && SKIP_SUBTREES.has(c.local))) walk(c);
+    }
+  };
+  walk(p);
+  return tags;
+}
+
+// Every paragraph of the body, in order: { style, text, tags }. A block-level
+// content control (the shape other editors may turn ours into) lends its tag to
+// the paragraphs inside it. Tables and other containers are walked into.
+function bodyParagraphs(body) {
+  const out = [];
+  const walk = (el, blockTags) => {
+    for (const c of kids(el)) {
+      if (c.ns === NS.mc && c.local === 'Fallback') continue;
+      if (isWEl(c, 'p')) {
+        const style = wVal(firstW(firstW(c, 'pPr'), 'pStyle'));
+        const tags = [...new Set([...blockTags, ...inlineTags(c)].filter((t) => LINE_KEY_RE.test(t)))];
+        out.push({ style: style || null, text: paragraphText(c), tags });
+      } else if (isWEl(c, 'sdt')) {
+        const tag = wVal(firstW(firstW(c, 'sdtPr'), 'tag'));
+        walk(firstW(c, 'sdtContent') || { children: [] }, tag != null ? [...blockTags, tag] : blockTags);
+      } else if (!(isW(c) && (c.local === 'sectPr' || SKIP_SUBTREES.has(c.local)))) {
+        walk(c, blockTags);
+      }
+    }
+  };
+  walk(body, []);
+  return out;
+}
+
+// readUpload(buf) -> { ok, page_id, reading_hash, paragraphs, baseline } | refusal
+//   not_a_docx       not a zip, not a Word document, or unreadable
+//   upload_too_large a part inflates past its cap
+function readUpload(buf) {
+  if (!Buffer.isBuffer(buf) || !buf.length) return fail('not_a_docx', { reason: 'the request carried no file' });
+  if (buf.length > MAX_UPLOAD_BYTES) return fail('upload_too_large', { max_bytes: MAX_UPLOAD_BYTES });
+  const want = (name) => name === '_rels/.rels' || /^word\/[^/]+\.xml$/i.test(name) || name === 'docProps/custom.xml' || /^customXml\/item\d+\.xml$/i.test(name);
+  const zip = readZip(buf, { want: (name) => want(name) });
+  if (!zip.ok) return zip;
+  try {
+    const rootRels = zip.parts.get('_rels/.rels');
+    const mainName = relTarget(rootRels && rootRels.toString('utf8'), REL.officeDocument) || 'word/document.xml';
+    const main = zip.parts.get(mainName);
+    if (!main) return fail('not_a_docx', { reason: 'the file has no Word document part' });
+    const docRoot = parseXml(main.toString('utf8'));
+    if (!isWEl(docRoot, 'document')) return fail('not_a_docx', { reason: 'the main part is not a Word document' });
+    const body = firstW(docRoot, 'body');
+    if (!body) return fail('not_a_docx', { reason: 'the Word document has no body' });
+    const propsName = relTarget(rootRels && rootRels.toString('utf8'), REL.customProps) || 'docProps/custom.xml';
+    const propsPart = zip.parts.get(propsName) || zip.parts.get('docProps/custom.xml');
+    const props = readCustomProps(propsPart ? propsPart.toString('utf8') : null);
+    let baseline = null;
+    const baselineParts = [...zip.parts.keys()].filter((n) => /^customXml\/item\d+\.xml$/i.test(n)).sort().slice(0, MAX_BASELINE_PARTS);
+    for (const n of baselineParts) {
+      try { baseline = readBaseline(zip.parts.get(n).toString('utf8')); } catch { baseline = null; }
+      if (baseline) break;
+    }
+    return {
+      ok: true,
+      page_id: typeof props.page_id === 'string' ? props.page_id : null,
+      reading_hash: typeof props.reading_hash === 'string' ? props.reading_hash : null,
+      paragraphs: bodyParagraphs(body),
+      baseline,
+    };
+  } catch (err) {
+    return fail('not_a_docx', { reason: `the file's XML is unreadable (${err.message})` });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// The upload: map paragraphs to lines, and refuse a changed structure by name.
+// ---------------------------------------------------------------------------
+
+function tidy(raw) {
+  return String(raw == null ? '' : raw).replace(/\s+/g, ' ').trim();
+}
+function firstWords(text, n = 6) {
+  const words = tidy(text).split(' ').filter(Boolean);
+  return words.length > n ? `${words.slice(0, n).join(' ')}…` : words.join(' ');
+}
+
+// Word turns every quote an artist types into a curly one (AutoFormat as you
+// type). The page's own text decides which it keeps: a line whose current text
+// has no curly quote is folded back to straight quotes, so a line is never
+// "changed" by an autocorrect alone and the page keeps its own convention.
+const CURLY_RE = /[\u2018\u2019\u201A\u201B\u201C\u201D\u201E\u201F]/;
+function foldQuotes(text) {
+  return String(text).replace(/[\u2018\u2019\u201A\u201B]/g, "'").replace(/[\u201C\u201D\u201E\u201F]/g, '"');
+}
+function pageQuotes(pageText, text) {
+  return CURLY_RE.test(pageText) ? text : foldQuotes(text);
+}
+
+// The keys NOT on the longest run of keys already in page order: the ones that
+// moved. (A line moved down reads as that one line moving, not as every line it
+// jumped over.)
+function movedKeys(keys, order) {
+  const idx = keys.map((k) => order.get(k));
+  const n = idx.length;
+  const len = new Array(n).fill(1);
+  const prev = new Array(n).fill(-1);
+  let best = -1;
+  for (let i = 0; i < n; i++) {
+    for (let j = 0; j < i; j++) if (idx[j] < idx[i] && len[j] + 1 > len[i]) { len[i] = len[j] + 1; prev[i] = j; }
+    if (best < 0 || len[i] > len[best]) best = i;
+  }
+  const keep = new Set();
+  for (let i = best; i >= 0; i = prev[i]) keep.add(keys[i]);
+  return keys.filter((k) => !keep.has(k));
+}
+
+function headingChanges(expected, found) {
+  const out = [];
+  for (let i = 0; i < Math.max(expected.length, found.length); i++) {
+    const e = i < expected.length ? expected[i] : null;
+    const f = i < found.length ? found[i] : null;
+    if (e !== f) out.push({ change: 'heading_changed', expected: e, found: f });
+  }
+  return out;
+}
+
+// mapUpload({ readingPage, upload }) -> { ok, mode, texts: Map(key -> text) } | structure_changed
+//
+// By TAG when any paragraph carries a line tag; by POSITION when every tag is
+// gone, which needs the same section headings and the same number of lines in
+// each. Paragraphs styled as the Title or the note, and empty untagged
+// paragraphs (an artist's spacing), are not lines.
+function mapUpload({ readingPage, upload }) {
+  const lines = readingPage.lines || [];
+  const byKey = new Map(lines.map((l) => [l.key, l]));
+  const order = new Map(lines.map((l, i) => [l.key, i]));
+  const runs = sectionRuns(lines);
+  const expectedHeadings = runs.map((r) => tidy(r.section));
+  const isHeading = (p) => /^heading\s*2$/i.test(String(p.style || ''));
+  const isFrame = (p) => /^title$/i.test(String(p.style || '')) || p.style === STYLE.note;
+  const paras = upload.paragraphs.filter((p) => !isFrame(p) && !(p.tags.length === 0 && !isHeading(p) && !tidy(p.text)));
+  const moved = [];
+  const named = (change, key, extra) => {
+    const l = byKey.get(key);
+    return { change, key, section: l ? (l.section == null ? null : l.section) : null, first_words: firstWords(l ? l.text : ''), ...(extra || {}) };
+  };
+  const refuse = () => fail('structure_changed', { mode, moved });
+
+  const tagged = paras.some((p) => p.tags.length);
+  const mode = tagged ? 'tag' : 'position';
+  if (tagged) {
+    const headings = [];
+    let heading = null;
+    const seen = [];
+    const texts = new Map();
+    for (const p of paras) {
+      if (isHeading(p) && !p.tags.length) { heading = tidy(p.text); headings.push(heading); continue; }
+      if (!p.tags.length) { moved.push({ change: 'added', key: null, section: heading, first_words: firstWords(p.text) }); continue; }
+      const [key, ...joined] = p.tags;
+      for (const other of joined) moved.push(named('dropped', other, { joined_to: key }));
+      if (!byKey.has(key) || texts.has(key)) {
+        moved.push({ change: 'added', key: byKey.has(key) ? key : null, section: heading, first_words: firstWords(p.text) });
+        continue;
+      }
+      seen.push(key);
+      texts.set(key, p.text);
+    }
+    for (const l of lines) if (!texts.has(l.key) && !moved.some((m) => m.key === l.key)) moved.push(named('dropped', l.key));
+    for (const key of movedKeys(seen, order)) moved.push(named('reordered', key));
+    moved.push(...headingChanges(expectedHeadings, headings));
+    if (moved.length) return refuse();
+    return { ok: true, mode, texts };
+  }
+
+  // By position: group the paragraphs under their headings.
+  const groups = [];
+  for (const p of paras) {
+    if (isHeading(p)) { groups.push({ section: tidy(p.text), paras: [] }); continue; }
+    if (!groups.length) groups.push({ section: null, paras: [] });
+    groups[groups.length - 1].paras.push(p);
+  }
+  const headingMoves = headingChanges(expectedHeadings, groups.map((g) => g.section));
+  if (headingMoves.length) { moved.push(...headingMoves); return refuse(); }
+  const texts = new Map();
+  runs.forEach((r, i) => {
+    const got = groups[i].paras;
+    got.slice(r.keys.length).forEach((p) => moved.push({ change: 'added', key: null, section: r.section, first_words: firstWords(p.text) }));
+    r.keys.slice(got.length).forEach((k) => moved.push(named('dropped', k)));
+    r.keys.forEach((k, j) => { if (j < got.length) texts.set(k, got[j].text); });
+  });
+  if (moved.length) return refuse();
+  return { ok: true, mode, texts };
+}
+
+// ---------------------------------------------------------------------------
+// The upload: merge into the draft.
+// ---------------------------------------------------------------------------
+
+// mergeUpload({ readingPage, texts, baseline, draft }) ->
+//   { lines: [{ key, after }], from_file: [keys], kept_from_draft: [keys] }
+//
+// With the file's baseline (the text each line was shown with at download), a
+// line is taken from the file only when the artist changed it there; every
+// other line keeps what the draft says now, so a rewrite made in the studio
+// after the download survives. Without it (an editor dropped the part), the
+// file is the whole intended state. The lines go to pages.resolveDraft, the
+// autosave's own resolver, which drops unchanged lines and takes every target
+// from the reading.
+function mergeUpload({ readingPage, texts, baseline, draft }) {
+  const draftAfter = new Map();
+  if (draft && draft.reading_hash === readingPage.reading_hash) {
+    for (const l of draft.lines || []) draftAfter.set(l.key, l.after);
+  }
+  const same = (a, b) => foldQuotes(tidy(a)) === foldQuotes(tidy(b));
+  const lines = [];
+  const fromFile = [];
+  const kept = [];
+  for (const l of readingPage.lines || []) {
+    const current = draftAfter.has(l.key) ? draftAfter.get(l.key) : l.text;
+    const uploaded = texts.has(l.key) ? tidy(pageQuotes(l.text, texts.get(l.key))) : current;
+    const changedInFile = baseline && baseline.has(l.key) ? !same(uploaded, baseline.get(l.key)) : !same(uploaded, current);
+    const after = changedInFile ? uploaded : current;
+    if (changedInFile && !same(after, current)) fromFile.push(l.key);
+    else if (draftAfter.has(l.key)) kept.push(l.key);
+    lines.push({ key: l.key, after });
+  }
+  return { lines, from_file: fromFile, kept_from_draft: kept };
+}
+
+module.exports = {
+  DOCX_MIME,
+  MAX_UPLOAD_BYTES,
+  MAX_PART_BYTES,
+  crc32,
+  writeZip,
+  readZip,
+  parseXml,
+  composeDownload,
+  downloadName,
+  readUpload,
+  mapUpload,
+  mergeUpload,
+};