@bongos/core 1.19.1061 → 1.19.1062

package/modules/copy-desk/pages.js

@@ -311,6 +311,21 @@ function sameDraft(saved, next) {
   return pick(saved) === pick(next);
 }
 
+// saveDraftInto(description, draft) -> { ok, description, draft } | refusal
+//
+// The one way a resolved draft is written into a round's description, shared by
+// the autosave (PUT .../draft) and the Word upload (POST .../draft.docx, task
+// 1004320), so both save through the same rules: the same draft again keeps the
+// stored block (saved_at included) and so writes nothing; no draft yet and
+// nothing changed stores nothing; otherwise the block is replaced in place.
+function saveDraftInto(description, draft) {
+  const prev = parseDraftBlock(description);
+  if (prev.ok && sameDraft(prev.draft, draft)) return { ok: true, description, draft: prev.draft };
+  if (prev.code === 'no_block' && !draft.lines.length) return { ok: true, description, draft };
+  const r = replaceBlock(description, FENCES.draft, composeDraftBlock(draft));
+  return r.ok ? { ok: true, description: r.description, draft } : r;
+}
+
 // Find a draft line on the CURRENT reading: the same key showing the same text,
 // else the one line showing that text in the same section, else the one line
 // showing it anywhere on the page. Anything else is gone, or too ambiguous to
@@ -431,6 +446,7 @@ module.exports = {
   replaceBlock,
   resolveDraft,
   sameDraft,
+  saveDraftInto,
   freezeBatch,
   unplacedSourceRef,
   unplacedTaskTitle,

package/modules/copy-desk/routes/copy-desk.js

@@ -14,6 +14,9 @@
 // task 1004317): POST /copy-desk/pages/:pageId/claim opens or takes a page's
 // tweak round as a TASK with a web claim, and POST /copy-desk/pages/:pageId/asks
 // files a page ask, a flag row whose target is a page id. Neither stores copy.
+// TW08 (task 1004319) added the draft autosave and the submit, and TW09 (task
+// 1004320) the Word round trip, GET and POST /copy-desk/pages/:pageId/draft.docx:
+// the upload lands in the round's DRAFT, through the autosave's own port call.
 //
 // THE RANK SHAPE, AND WHY IT IS ASYMMETRIC:
 //
@@ -53,6 +56,7 @@ const proposals = require('../proposals');
 const pageData = require('../page-data');
 const pageStatus = require('../page-status');
 const pages = require('../pages');
+const docx = require('../docx');
 
 const { validateOrRespond } = api;
 
@@ -125,6 +129,10 @@ const PAGE_REFUSAL_STATUS = Object.freeze({
   block_schema_unknown: 409,
   block_field_missing: 409,
   wrong_page: 409,
+  // The Word upload (task 1004320, ADR 0341 D12).
+  structure_changed: 409,
+  not_a_docx: 415,
+  upload_too_large: 413,
 });
 const PAGE_REFUSAL_MEANS = Object.freeze({
   reading_moved: 'The page changed since the editor loaded it, so a line key may now mean a different line. Reload the page to get the current reading; nothing was saved.',
@@ -133,7 +141,27 @@ const PAGE_REFUSAL_MEANS = Object.freeze({
   line_too_long: `A line holds at most ${pages.MAX_LINE_CHARS} characters.`,
   lines_refused: 'Some lines cannot be frozen as written: the page no longer shows them (target_gone), shows the same words in more than one place (ambiguous_target), or the rewrite dropped or added a {…} hole (placeholder_mismatch). Fix or remove each named line and submit again; nothing was submitted.',
   nothing_to_submit: 'The draft has no rewritten lines yet.',
+  structure_changed: 'The file\'s lines no longer match the page: a paragraph was added, removed or moved, or a heading changed. Each one is listed. Put them back (one paragraph per line, in the page\'s order) or download the page again, and upload once more; nothing was saved.',
+  not_a_docx: 'Upload the .docx file this page downloaded, as the request body. Nothing was saved.',
+  upload_too_large: `A page file is at most ${Math.round(docx.MAX_UPLOAD_BYTES / (1024 * 1024))} MB. Nothing was saved.`,
 });
+// The upload's answers when the file is readable but is not this page's, or not
+// this reading's (task 1004320, ADR 0341 D12).
+const UPLOAD_WRONG_PAGE_MEANS = 'This file is not the download of this page, or the program that saved it dropped the page details Word keeps. Download this page again and make your changes in that file. Nothing was saved.';
+const UPLOAD_READING_MOVED_MEANS = 'The page has changed since this file was downloaded, so its lines may no longer line up with the page. Download the page again and copy your changes across. Nothing was saved.';
+
+// The upload's body is the .docx itself, never JSON (the global parser only
+// reads application/json, so it passes this through). Capped at the parser, and
+// never inflated from a Content-Encoding, so the cap is the bytes on the wire.
+const DOCX_BODY_TYPES = [docx.DOCX_MIME, 'application/zip', 'application/x-zip-compressed', 'application/octet-stream'];
+const rawDocxBody = express.raw({ type: DOCX_BODY_TYPES, limit: docx.MAX_UPLOAD_BYTES, inflate: false });
+function docxBody(req, res, next) {
+  rawDocxBody(req, res, (err) => {
+    if (!err) return next();
+    if (err.type === 'entity.too.large') return refusePage(res, { code: 'upload_too_large', detail: { max_bytes: docx.MAX_UPLOAD_BYTES } });
+    return refusePage(res, { code: 'not_a_docx', detail: { reason: 'the upload could not be read' } });
+  });
+}
 
 function refusePage(res, r) {
   const status = PAGE_REFUSAL_STATUS[r.code] || 400;
@@ -999,16 +1027,12 @@ module.exports = function buildCopyDeskRouter() {
         taskId: round.id,
         builderId: req.builder.id,
         source: pages.SOURCE,
+        // The same draft again keeps the stored block (saved_at included) and
+        // writes nothing; see pages.saveDraftInto, which the upload shares.
         compose: (task) => {
-          const prev = pages.parseDraftBlock(task.description);
-          // The same draft again: keep the stored block, saved_at included.
-          if (prev.ok && pages.sameDraft(prev.draft, resolved.draft)) {
-            draft = prev.draft;
-            return { ok: true, description: task.description };
-          }
-          // No draft yet and nothing changed: there is nothing to store.
-          if (prev.code === 'no_block' && !resolved.draft.lines.length) return { ok: true, description: task.description };
-          return pages.replaceBlock(task.description, pages.FENCES.draft, pages.composeDraftBlock(resolved.draft));
+          const s = pages.saveDraftInto(task.description, resolved.draft);
+          if (s.ok) draft = s.draft;
+          return s;
         },
       });
       switch (r.outcome) {
@@ -1036,6 +1060,141 @@ module.exports = function buildCopyDeskRouter() {
     }
   });
 
+  // -------------------------------------------------------------------------
+  // GET /copy-desk/pages/:pageId/draft.docx — download the page's words as a
+  // Word document, to work on offline (task 1004320 / BV2.TW09, ADR 0341 D12).
+  //
+  // The file is built from the page reading plus the open round's draft (a line
+  // the artist has rewritten shows its rewrite). A draft saved on an older
+  // reading is not shown, since its keys may now name other lines.
+  // rank: any signed-in builder. The words are the page's own, and the draft is
+  //       on a task description every builder can already read; only the
+  //       upload is the holder's.
+  // -------------------------------------------------------------------------
+  router.get('/copy-desk/pages/:pageId/draft.docx', api.requireBuilder, async (req, res) => {
+    try {
+      const found = pageOrFail(req, res);
+      if (!found) return;
+      const { page, pageId } = found;
+      const lifecycle = pageReadsOrFail(res);
+      if (!lifecycle) return;
+      const readingPage = readingPageOrFail(res, pageId);
+      if (!readingPage) return;
+      const round = openRoundOf(await lifecycle.listPageTweakTasks({ pageId }), pageId);
+      const d = round ? pages.parseDraftBlock(round.description) : null;
+      const file = docx.composeDownload({ readingPage, title: page.title, draft: d && d.ok ? d.draft : null });
+      res.set('Content-Type', docx.DOCX_MIME);
+      res.set('Content-Disposition', `attachment; filename="${docx.downloadName(pageId)}"`);
+      res.set('Cache-Control', 'no-store');
+      res.send(file);
+    } catch (err) {
+      log.error({ err }, 'GET /copy-desk/pages/:pageId/draft.docx failed');
+      if (!res.headersSent) res.fail('copy_page_docx_failed', 500);
+    }
+  });
+
+  // -------------------------------------------------------------------------
+  // POST /copy-desk/pages/:pageId/draft.docx — upload the Word file back into
+  // the DRAFT (task 1004320 / BV2.TW09, ADR 0341 D12). Never to the site: the
+  // words land in the round's draft block, exactly where the autosave puts
+  // them, through the same port call (holder only) and the same resolver
+  // (every target from the page reading by key, never from the file).
+  //
+  // Body: the .docx bytes (Content-Type: the Word type, application/zip or
+  //       application/octet-stream), at most docx.MAX_UPLOAD_BYTES.
+  // rank: any signed-in builder; only the HOLDER of the page's writing claim.
+  //
+  // A MERGE, not a replace: a line is taken from the file only when the artist
+  // changed it in Word (against the text the download showed), so a line they
+  // rewrote in the studio after downloading keeps that rewrite.
+  //
+  //   200 saved | unchanged   the draft, the counter, and `merge` (which lines
+  //                           came from the file, and how they were matched)
+  //   409 structure_changed   a line added, dropped or reordered, or a heading
+  //                           changed; each is named (section, first words)
+  //   409 wrong_page · reading_moved · page_not_held · no_open_round
+  //   413 upload_too_large · 415 not_a_docx
+  // -------------------------------------------------------------------------
+  router.post('/copy-desk/pages/:pageId/draft.docx', api.requireBuilder, docxBody, async (req, res) => {
+    try {
+      const found = pageOrFail(req, res);
+      if (!found) return;
+      const { pageId } = found;
+      const lifecycle = pageReadsOrFail(res);
+      if (!lifecycle) return;
+      if (typeof lifecycle.updateHeldTaskDescription !== 'function') {
+        return res.fail('lifecycle_unavailable', 503, { what_this_means: 'This instance cannot save a page draft. Nothing was saved.' });
+      }
+      const readingPage = readingPageOrFail(res, pageId);
+      if (!readingPage) return;
+
+      const upload = docx.readUpload(Buffer.isBuffer(req.body) ? req.body : null);
+      if (!upload.ok) return refusePage(res, upload);
+      if (upload.page_id !== pageId) {
+        return res.fail('wrong_page', 409, { page_id: pageId, file_page_id: upload.page_id, what_this_means: UPLOAD_WRONG_PAGE_MEANS });
+      }
+      if (upload.reading_hash !== readingPage.reading_hash) {
+        return res.fail('reading_moved', 409, { reading_hash: readingPage.reading_hash || null, file_reading_hash: upload.reading_hash, what_this_means: UPLOAD_READING_MOVED_MEANS });
+      }
+      const mapped = docx.mapUpload({ readingPage, upload });
+      if (!mapped.ok) return refusePage(res, mapped);
+
+      const round = openRoundOf(await lifecycle.listPageTweakTasks({ pageId }), pageId);
+      if (!round) {
+        return res.fail('no_open_round', 409, {
+          page_id: pageId,
+          what_this_means: 'Nobody is writing this page. Claim it first (POST /copy-desk/pages/:pageId/claim), then upload the file.',
+        });
+      }
+
+      const savedAt = new Date().toISOString();
+      let draft = null;
+      let merge = null;
+      const r = await lifecycle.updateHeldTaskDescription({
+        taskId: round.id,
+        builderId: req.builder.id,
+        source: pages.SOURCE,
+        // Merged on the LOCKED task, so the draft the file merges into is the
+        // one stored now, not one read before the lock.
+        compose: (task) => {
+          const prev = pages.parseDraftBlock(task.description);
+          const m = docx.mergeUpload({ readingPage, texts: mapped.texts, baseline: upload.baseline, draft: prev.ok ? prev.draft : null });
+          const resolved = pages.resolveDraft({ readingPage, body: { reading_hash: readingPage.reading_hash, lines: m.lines }, savedAt });
+          if (!resolved.ok) return resolved;
+          const s = pages.saveDraftInto(task.description, resolved.draft);
+          if (s.ok) { draft = s.draft; merge = m; }
+          return s;
+        },
+      });
+      switch (r.outcome) {
+        case 'saved':
+        case 'unchanged':
+          return res.json({
+            ok: true,
+            outcome: r.outcome,
+            page_id: pageId,
+            round: { task_id: String(round.id), state: 'writing' },
+            draft: { reading_hash: draft.reading_hash, saved_at: draft.saved_at, lines: draft.lines },
+            counter: { changed: draft.lines.length, total: readingPage.lines.length },
+            // What the editor shows after an upload ("uploaded · 3 lines from
+            // your doc", Editor.dc.html): the lines the file changed, the draft
+            // lines it left alone, and whether lines were matched by tag or by
+            // position, with or without the file's record of what it showed.
+            merge: { mode: mapped.mode, baseline: !!upload.baseline, from_file: merge.from_file, kept_from_draft: merge.kept_from_draft },
+          });
+        case 'not_held':
+          return refuseNotHeld(res, pageId, r, round);
+        case 'refused':
+          return refusePage(res, r.refusal);
+        default:
+          throw new Error(`updateHeldTaskDescription: unexpected outcome ${r.outcome}`);
+      }
+    } catch (err) {
+      log.error({ err }, 'POST /copy-desk/pages/:pageId/draft.docx failed');
+      if (!res.headersSent) res.fail('copy_page_docx_upload_failed', 500);
+    }
+  });
+
   // -------------------------------------------------------------------------
   // POST /copy-desk/pages/:pageId/submit — freeze the draft and queue the page
   // for /tweak (task 1004319 / BV2.TW08, ADR 0341 D4, D7).

package/modules/copy-desk/tests/copy_docx.mjs

@@ -0,0 +1,347 @@
+// modules/copy-desk/tests/copy_docx.mjs — the Word round trip, pure (task
+// 1004320 / BV2.TW09, ADR 0341 D12).
+//
+// What docx.js must do before any route is involved: write a file Word can
+// open with one tagged paragraph per line; read an upload the way Word stores
+// an edit (runs split across <w:r> elements, proofing marks, smart quotes,
+// tracked changes, a data-descriptor zip); map it back by tag or by position;
+// merge it into a draft without losing a rewrite made after the download; and
+// refuse by name every change of structure. And bound every read of an
+// upload, which is someone else's input.
+//
+// The whole path (the routes, the holder check, the draft block on the task)
+// is tests/copy_desk_page_docx.mjs (root).
+
+import { strict as assert } from 'node:assert';
+import zlib from 'node:zlib';
+import { createRequire } from 'node:module';
+import { unzipAll, wordZip, resave, typeInto, wordRuns, trackedInsert, trackedDelete, stripControls, lineParagraph } from './fixtures/word-docx.mjs';
+
+const require = createRequire(import.meta.url);
+const docx = require('../docx.js');
+const pages = require('../pages.js');
+
+let passed = 0;
+let failed = 0;
+function test(name, fn) {
+  try { fn(); passed++; console.log(`  ok  ${name}`); }
+  catch (err) { failed++; console.log(`  FAIL ${name}`); console.log(`     ${err.stack || err.message}`); }
+}
+
+const L = (key, section, text, placement, row) => ({ key, section, text, placement, ...(row || {}) });
+const READING = {
+  id: 'builders:studio',
+  title: 'Studio',
+  reading_hash: 'h-now',
+  lines: [
+    L('L0001', 'top bar', 'Studio', 'shared', { file: 'shell.js', line: 40, string_id: 'sh01' }),
+    L('L0002', 'greeting', 'Welcome back', 'placed', { file: 'studio.html', line: 12, string_id: 'st02' }),
+    L('L0003', 'greeting', '{…} pages tweaked', 'placed', { file: 'studio.js', line: 88, string_id: 'st03' }),
+    L('L0004', 'greeting', 'Your desk is quiet today', 'unplaced'),
+    L('L0005', 'greeting', 'It\u2019s your turn', 'placed', { file: 'studio.js', line: 90, string_id: 'st05' }),
+    L('L0006', 'footer', 'Resume', 'placed', { file: 'studio.html', line: 99, string_id: 'st06' }),
+    // A section that recurs later on the page gets its heading again.
+    L('L0007', 'greeting', 'Take the next page', 'placed', { file: 'studio.html', line: 120, string_id: 'st07' }),
+  ],
+};
+const download = (draft = null) => docx.composeDownload({ readingPage: READING, title: 'Studio', draft });
+const upload = (buf) => {
+  const u = docx.readUpload(buf);
+  assert.equal(u.ok, true, JSON.stringify(u));
+  return u;
+};
+const roundTrip = (buf, draft = null) => {
+  const u = upload(buf);
+  const m = docx.mapUpload({ readingPage: READING, upload: u });
+  if (!m.ok) return { mapped: m };
+  return { mapped: m, merged: docx.mergeUpload({ readingPage: READING, texts: m.texts, baseline: u.baseline, draft }) };
+};
+const draftOf = (lines) => ({ page_id: READING.id, reading_hash: READING.reading_hash, saved_at: 't', lines });
+
+console.log('copy-desk: the Word round trip');
+
+// ---------------------------------------------------------------------------
+// The zip, both directions, and the bounds on an upload.
+// ---------------------------------------------------------------------------
+
+test('the zip writer and reader agree, and the reader takes a Word-shaped zip (data descriptors)', () => {
+  const entries = [{ name: 'a.xml', data: '<a>é…</a>' }, { name: 'dir/b.xml', data: 'x'.repeat(5000) }];
+  const z = docx.readZip(docx.writeZip(entries));
+  assert.equal(z.ok, true);
+  assert.deepEqual([...z.parts].map(([k, v]) => [k, v.toString('utf8')]), entries.map((e) => [e.name, e.data]));
+  const w = docx.readZip(wordZip([['one.xml', '<one/>'], ['two.xml', 'two'.repeat(99)]]));
+  assert.equal(w.ok, true, JSON.stringify(w));
+  assert.equal(w.parts.get('two.xml').toString(), 'two'.repeat(99));
+  assert.equal(docx.crc32(Buffer.from('123456789')), 0xCBF43926, 'the standard CRC-32 check value');
+});
+
+test('the same page makes the same bytes', () => {
+  assert.equal(Buffer.compare(download(), download()), 0);
+});
+
+test('an upload that is not a zip, or a broken one, is not_a_docx', () => {
+  for (const bad of [Buffer.from('{"lines":[]}'), Buffer.from('PK\u0003\u0004 not really'), Buffer.alloc(0)]) {
+    assert.equal(docx.readUpload(bad).code, 'not_a_docx', bad.toString());
+  }
+  // A flipped byte inside the document part's deflated data fails its CRC (or
+  // its inflate). The first match is the local header's copy of the name.
+  const buf = Buffer.from(download());
+  const at = buf.indexOf('word/document.xml') + 'word/document.xml'.length + 40;
+  buf[at] ^= 0xFF;
+  assert.equal(docx.readUpload(buf).code, 'not_a_docx');
+  // A zip that is not a Word document.
+  assert.equal(docx.readUpload(docx.writeZip([{ name: 'hello.txt', data: 'hi' }])).detail.reason, 'the file has no Word document part');
+});
+
+test('an encrypted entry is refused, never guessed at', () => {
+  const buf = Buffer.from(download());
+  // Set the encryption flag on every central directory entry.
+  for (let i = 0; i < buf.length - 4; i++) if (buf.readUInt32LE(i) === 0x02014b50) buf.writeUInt16LE(buf.readUInt16LE(i + 8) | 1, i + 8);
+  const r = docx.readUpload(buf);
+  assert.equal(r.code, 'not_a_docx');
+  assert.match(r.detail.reason, /encrypted/);
+});
+
+test('a zip bomb stops at the part cap, and an oversized file is refused before it is read', () => {
+  // 9 MB of zeros deflates to a few kilobytes: the declared size is refused,
+  // and a lying declared size is stopped by the inflate cap itself.
+  const zeros = Buffer.alloc(docx.MAX_PART_BYTES + 1024 * 1024);
+  const honest = docx.writeZip([{ name: 'word/document.xml', data: zeros }]);
+  assert.ok(honest.length < 100 * 1024);
+  assert.equal(docx.readUpload(honest).code, 'upload_too_large');
+  const liar = Buffer.from(honest);
+  for (let i = 0; i < liar.length - 4; i++) if (liar.readUInt32LE(i) === 0x02014b50) liar.writeUInt32LE(10, i + 24);
+  assert.equal(docx.readZip(liar).code, 'upload_too_large');
+  assert.equal(docx.readUpload(Buffer.alloc(docx.MAX_UPLOAD_BYTES + 1, 1)).code, 'upload_too_large');
+});
+
+test('a DOCTYPE (an entity expansion) is refused, and entities are not expanded', () => {
+  const doctype = resave(download(), { document: (xml) => xml.replace('<w:document', '<!DOCTYPE d [<!ENTITY x "boom">]><w:document') });
+  assert.equal(docx.readUpload(doctype).code, 'not_a_docx');
+  assert.equal(docx.parseXml('<a>&amp;lt; &#x2019; &unknown;</a>').children[0], '&lt; \u2019 &unknown;');
+});
+
+// ---------------------------------------------------------------------------
+// The download.
+// ---------------------------------------------------------------------------
+
+test('the download: title, a Heading 2 per run of a section, one tagged plain-text control per line', () => {
+  const doc = unzipAll(download()).get('word/document.xml');
+  const paras = [...doc.matchAll(/<w:p>(.*?)<\/w:p>/gs)].map((m) => m[1]);
+  const style = (p) => (/<w:pStyle w:val="([^"]+)"/.exec(p) || [])[1] || null;
+  const text = (p) => [...p.matchAll(/<w:t[^>]*>([^<]*)<\/w:t>/g)].map((m) => m[1]).join('');
+  assert.deepEqual([style(paras[0]), text(paras[0])], ['Title', 'Studio']);
+  assert.equal(style(paras[1]), 'TweakNote');
+  const headings = paras.filter((p) => style(p) === 'Heading2').map(text);
+  assert.deepEqual(headings, ['top bar', 'greeting', 'footer', 'greeting']);
+  const lines = paras.filter((p) => /<w:tag /.test(p));
+  assert.deepEqual(lines.map((p) => /<w:tag w:val="([^"]+)"/.exec(p)[1]), READING.lines.map((l) => l.key));
+  for (const p of lines) assert.match(p, /<w:sdtPr><w:tag w:val="L\d{4}"\/><w:id w:val="\d+"\/><w:text\/><\/w:sdtPr>/, 'a plain-text control');
+  assert.equal(text(lines[4]), 'It\u2019s your turn');
+});
+
+test('shared and unplaced lines carry their own style and a margin comment', () => {
+  const parts = unzipAll(download());
+  const doc = parts.get('word/document.xml');
+  assert.match(lineParagraph(doc, 'L0001'), /<w:pStyle w:val="TweakShared"\/>.*<w:commentReference w:id="0"\/>/s);
+  assert.match(lineParagraph(doc, 'L0004'), /<w:pStyle w:val="TweakUnplaced"\/>.*<w:commentReference w:id="1"\/>/s);
+  assert.doesNotMatch(lineParagraph(doc, 'L0002'), /pStyle|comment/);
+  const comments = [...parts.get('word/comments.xml').matchAll(/<w:comment w:id="(\d)".*?<w:t[^>]*>([^<]*)<\/w:t>/gs)].map((m) => [m[1], m[2]]);
+  assert.deepEqual(comments, [['0', 'changes this on every page'], ['1', 'goes to an engineer']]);
+  assert.match(parts.get('word/styles.xml'), /w:styleId="TweakShared"/);
+  assert.match(parts.get('word/styles.xml'), /w:styleId="Heading2"><w:name w:val="heading 2"\/>/, 'the built-in Heading 2, so Word lists it as one');
+});
+
+test('page_id and reading_hash are custom document properties', () => {
+  const u = upload(download());
+  assert.equal(u.page_id, 'builders:studio');
+  assert.equal(u.reading_hash, 'h-now');
+  assert.match(unzipAll(download()).get('docProps/custom.xml'), /name="page_id"><vt:lpwstr>builders:studio<\/vt:lpwstr>/);
+});
+
+test('the download shows the draft over the reading, and ignores a draft saved on another reading', () => {
+  const draft = draftOf([{ key: 'L0002', section: 'greeting', before: 'Welcome back', after: 'Welcome home', placement: 'placed' }]);
+  assert.equal(upload(download(draft)).baseline.get('L0002'), 'Welcome home');
+  assert.match(unzipAll(download(draft)).get('word/document.xml'), />Welcome home</);
+  const stale = { ...draft, reading_hash: 'h-old' };
+  assert.doesNotMatch(unzipAll(download(stale)).get('word/document.xml'), />Welcome home</);
+});
+
+test('an untouched round trip changes nothing on every line', () => {
+  const { mapped, merged } = roundTrip(download());
+  assert.equal(mapped.mode, 'tag');
+  assert.deepEqual(merged.from_file, []);
+  const resolved = pages.resolveDraft({ readingPage: READING, body: { reading_hash: 'h-now', lines: merged.lines }, savedAt: 't' });
+  assert.deepEqual(resolved.draft.lines, []);
+});
+
+// ---------------------------------------------------------------------------
+// Reading an edit the way Word stores it.
+// ---------------------------------------------------------------------------
+
+test('Word splits one edited line across many runs: the upload reads the whole sentence', () => {
+  const edited = resave(download(), { document: (xml) => typeInto(xml, 'L0002', wordRuns(['Wel', 'come ', 'ho', 'me, ', 'friend'])) });
+  const { merged } = roundTrip(edited);
+  assert.deepEqual(merged.from_file, ['L0002']);
+  assert.equal(merged.lines.find((l) => l.key === 'L0002').after, 'Welcome home, friend');
+});
+
+test('smart quotes: folded back on a line the page writes with straight quotes, kept on one written curly', () => {
+  const edited = resave(download(), {
+    document: (xml) => typeInto(typeInto(xml, 'L0002', wordRuns(['Welcome back, it\u2019s \u201Cyour\u201D desk'])),
+      'L0005', wordRuns(['It\u2019s ', 'your go'])),
+  });
+  const { merged } = roundTrip(edited);
+  const after = (k) => merged.lines.find((l) => l.key === k).after;
+  assert.equal(after('L0002'), 'Welcome back, it\'s "your" desk');
+  assert.equal(after('L0005'), 'It\u2019s your go');
+  // An autocorrect alone (a quote retyped, nothing else) is not a change.
+  const retyped = resave(download(), { document: (xml) => typeInto(xml, 'L0005', wordRuns(['It\'s your turn'])) });
+  assert.deepEqual(roundTrip(retyped).merged.from_file, []);
+});
+
+test('tracked changes read as accepted: an insertion is text, a deletion is not', () => {
+  const edited = resave(download(), {
+    document: (xml) => typeInto(xml, 'L0006', `${wordRuns(['Resume '])}${trackedDelete('now')}${trackedInsert('where you left off')}`),
+  });
+  assert.equal(roundTrip(edited).merged.lines.find((l) => l.key === 'L0006').after, 'Resume where you left off');
+});
+
+test('a tab, a line break and a different namespace prefix still read as the words', () => {
+  const edited = resave(download(), {
+    document: (xml) => typeInto(xml, 'L0002', '<w:r><w:t>Welcome</w:t><w:tab/><w:t>in</w:t><w:br/><w:t>here</w:t></w:r>')
+      .replace(/xmlns:w=/, 'xmlns:ww=').replace(/<(\/?)w:/g, '<$1ww:').replace(/ w:/g, ' ww:'),
+  });
+  assert.equal(roundTrip(edited).merged.lines.find((l) => l.key === 'L0002').after, 'Welcome in here');
+});
+
+// ---------------------------------------------------------------------------
+// The merge.
+// ---------------------------------------------------------------------------
+
+test('the merge keeps a rewrite made in the studio after the download', () => {
+  const file = download(); // shows the page's own text everywhere
+  const edited = resave(file, { document: (xml) => typeInto(xml, 'L0006', wordRuns(['Pick up ', 'where you were'])) });
+  // Since the download, the artist rewrote L0002 in the studio.
+  const draft = draftOf([{ key: 'L0002', section: 'greeting', before: 'Welcome back', after: 'Hello again', placement: 'placed' }]);
+  const { merged } = roundTrip(edited, draft);
+  const after = (k) => merged.lines.find((l) => l.key === k).after;
+  assert.equal(after('L0002'), 'Hello again', 'the file did not touch L0002, so the draft keeps it');
+  assert.equal(after('L0006'), 'Pick up where you were');
+  assert.deepEqual(merged.from_file, ['L0006']);
+  assert.deepEqual(merged.kept_from_draft, ['L0002']);
+});
+
+test('a line changed in Word wins over the draft; without the file\'s baseline the file is the whole state', () => {
+  const draft = draftOf([{ key: 'L0002', section: 'greeting', before: 'Welcome back', after: 'Hello again', placement: 'placed' }]);
+  const edited = resave(download(), { document: (xml) => typeInto(xml, 'L0002', wordRuns(['Hi there'])) });
+  assert.equal(roundTrip(edited, draft).merged.lines.find((l) => l.key === 'L0002').after, 'Hi there');
+  // An editor that drops the custom XML part: every line is what the file says,
+  // so the studio rewrite of L0002 is replaced by the page text the file shows.
+  const noBaseline = resave(download(), { drop: ['customXml/item1.xml'] });
+  const u = upload(noBaseline);
+  assert.equal(u.baseline, null);
+  const { merged } = roundTrip(noBaseline, draft);
+  assert.equal(merged.lines.find((l) => l.key === 'L0002').after, 'Welcome back');
+  assert.deepEqual(merged.from_file, ['L0002']);
+});
+
+// ---------------------------------------------------------------------------
+// Structure changes are refused, by name.
+// ---------------------------------------------------------------------------
+
+const refusal = (buf) => {
+  const { mapped } = roundTrip(buf);
+  assert.equal(mapped.ok, false);
+  assert.equal(mapped.code, 'structure_changed');
+  return mapped.detail.moved;
+};
+
+test('an added paragraph is named by its section and first words', () => {
+  const buf = resave(download(), {
+    document: (xml) => { const p = lineParagraph(xml, 'L0002'); return xml.replace(p, () => `${p}<w:p><w:r><w:t>A brand new line nobody asked for today</w:t></w:r></w:p>`); },
+  });
+  assert.deepEqual(refusal(buf), [{ change: 'added', key: null, section: 'greeting', first_words: 'A brand new line nobody asked…' }]);
+});
+
+test('a dropped line is named by its key, section and first words', () => {
+  const buf = resave(download(), { document: (xml) => xml.replace(lineParagraph(xml, 'L0004'), '') });
+  assert.deepEqual(refusal(buf), [{ change: 'dropped', key: 'L0004', section: 'greeting', first_words: 'Your desk is quiet today' }]);
+});
+
+test('a moved line is named, and only the line that moved', () => {
+  const buf = resave(download(), {
+    document: (xml) => { const p = lineParagraph(xml, 'L0002'); return xml.replace(p, '').replace(lineParagraph(xml, 'L0004'), (q) => `${q}${p}`); },
+  });
+  assert.deepEqual(refusal(buf), [{ change: 'reordered', key: 'L0002', section: 'greeting', first_words: 'Welcome back' }]);
+});
+
+test('a copied control is an added line; two lines joined into one paragraph drop the second', () => {
+  const copied = resave(download(), { document: (xml) => { const p = lineParagraph(xml, 'L0006'); return xml.replace(p, () => `${p}${p}`); } });
+  assert.deepEqual(refusal(copied), [{ change: 'added', key: 'L0006', section: 'footer', first_words: 'Resume' }]);
+  const joined = resave(download(), {
+    document: (xml) => {
+      const a = lineParagraph(xml, 'L0002');
+      const b = lineParagraph(xml, 'L0003');
+      const sdtB = /<w:sdt>.*<\/w:sdt>/s.exec(b)[0];
+      return xml.replace(b, '').replace(a, () => a.replace('</w:p>', `${sdtB}</w:p>`));
+    },
+  });
+  assert.deepEqual(refusal(joined), [{ change: 'dropped', key: 'L0003', section: 'greeting', first_words: '{…} pages tweaked', joined_to: 'L0002' }]);
+});
+
+test('a changed section heading is refused', () => {
+  const buf = resave(download(), { document: (xml) => xml.replace('<w:t xml:space="preserve">footer</w:t>', '<w:t>Footer bits</w:t>') });
+  assert.deepEqual(refusal(buf), [{ change: 'heading_changed', expected: 'footer', found: 'Footer bits' }]);
+});
+
+test('empty paragraphs (spacing) and the title and note are not lines', () => {
+  const buf = resave(download(), {
+    document: (xml) => { const p = lineParagraph(xml, 'L0002'); return xml.replace(p, () => `<w:p/>${p}<w:p><w:r><w:t> </w:t></w:r></w:p>`).replace('>Studio</w:t></w:r></w:p>', '>My studio notes</w:t></w:r></w:p>'); },
+  });
+  const { mapped } = roundTrip(buf);
+  assert.equal(mapped.ok, true, JSON.stringify(mapped.detail));
+});
+
+// ---------------------------------------------------------------------------
+// When every tag is gone: by position.
+// ---------------------------------------------------------------------------
+
+test('with the controls stripped, lines map by position under the same headings', () => {
+  const buf = resave(download(), { document: (xml) => stripControls(typeInto(xml, 'L0006', wordRuns(['Carry ', 'on']))) });
+  assert.doesNotMatch(unzipAll(buf).get('word/document.xml'), /<w:tag /);
+  const { mapped, merged } = roundTrip(buf);
+  assert.equal(mapped.mode, 'position');
+  assert.deepEqual(merged.from_file, ['L0006']);
+  assert.equal(merged.lines.find((l) => l.key === 'L0006').after, 'Carry on');
+});
+
+test('by position, a section with a line more or a line fewer is refused and named', () => {
+  const extra = resave(download(), {
+    document: (xml) => { const p = lineParagraph(xml, 'L0006'); return stripControls(xml.replace(p, () => `${p}<w:p><w:r><w:t>Another line</w:t></w:r></w:p>`)); },
+  });
+  assert.deepEqual(refusal(extra), [{ change: 'added', key: null, section: 'footer', first_words: 'Another line' }]);
+  const fewer = resave(download(), { document: (xml) => stripControls(xml.replace(lineParagraph(xml, 'L0006'), '')) });
+  assert.deepEqual(refusal(fewer), [{ change: 'dropped', key: 'L0006', section: 'footer', first_words: 'Resume' }]);
+  const heading = resave(download(), { document: (xml) => stripControls(xml.replace('<w:t xml:space="preserve">top bar</w:t>', '<w:t>Top</w:t>')) });
+  assert.equal(refusal(heading)[0].change, 'heading_changed');
+});
+
+// ---------------------------------------------------------------------------
+// Every page the inventory reads round-trips untouched.
+// ---------------------------------------------------------------------------
+
+test('every committed page reading round-trips with no change', () => {
+  const readings = require('../../../docs/page-readings.json');
+  for (const p of readings.pages) {
+    const u = docx.readUpload(docx.composeDownload({ readingPage: p, title: p.title, draft: null }));
+    assert.equal(u.ok, true, p.id);
+    const m = docx.mapUpload({ readingPage: p, upload: u });
+    assert.equal(m.ok, true, `${p.id}: ${JSON.stringify(m.detail)}`);
+    assert.deepEqual(docx.mergeUpload({ readingPage: p, texts: m.texts, baseline: u.baseline, draft: null }).from_file, [], p.id);
+  }
+  assert.ok(zlib, 'node:zlib is the only dependency');
+});
+
+console.log(`\ncopy_docx: ${passed} passed, ${failed} failed`);
+process.exit(failed ? 1 : 0);