@bongos/core 1.19.1061 → 1.19.1063

package/scripts/hall-preview/server.js

@@ -132,6 +132,22 @@ const FIXTURE_FALLBACKS = [
   // the npm-release module's line on a task's page (task 1004301): one reading serves any
   // id, as the core-upgrade preview above does — the page shows one task.
   [/^npm-release\/task\/\d+$/, 'npm-release__task'],
+  // the tweak editor's read (task 1004321): one page's lines and draft serve any
+  // page id, since the editor shows one page. A page id carries a colon, which a
+  // Windows file name cannot, so there is no per-id file to find first.
+  [/^copy-desk\/pages\/[a-z0-9-]+:[a-z0-9-]+\/draft$/, 'copy-desk__pages__draft'],
+];
+
+// CANNED WRITES (task 1004321). The tweak editor's whole flow is writes (the
+// autosave, the submit, the claim "take next" posts), so without an answer the
+// harness could only ever show its "not saved" state, never the page the
+// artboard draws after a save or a submit. Each member answers a FIXED fixture
+// and changes nothing: the harness has no state to change, and the page reads
+// the same fixtures again on reload. Anything absent is still refused.
+const CANNED_WRITES = [
+  ['PUT', /^copy-desk\/pages\/[a-z0-9-]+:[a-z0-9-]+\/draft$/, 'copy-desk__pages__draft.put'],
+  ['POST', /^copy-desk\/pages\/[a-z0-9-]+:[a-z0-9-]+\/submit$/, 'copy-desk__pages__submit.post'],
+  ['POST', /^copy-desk\/pages\/[a-z0-9-]+:[a-z0-9-]+\/claim$/, 'copy-desk__pages__claim.post'],
 ];
 
 // A DATE THAT ROTS CANNOT DEMO AN AGE SIGNAL (task 1004041). The help-request
@@ -254,6 +270,11 @@ app.use((req, res, next) => {
   const READ_SHAPED_POSTS = new Set([
     'inbox/preview-landing', // the landing verdict for a draft (task 1004083)
   ]);
+  const canned = CANNED_WRITES.find(([method, re]) => method === req.method && re.test(apiPath));
+  if (canned) {
+    const hit = loadFixture(canned[2]);
+    if (hit !== undefined) return res.json(hit);
+  }
   if (req.method !== 'GET' && !READ_SHAPED_POSTS.has(apiPath)) {
     return res.status(501).json({ error: { code: 'preview_readonly', message: 'the preview harness serves fixtures; writes are not wired' } });
   }

package/src/bongos/serve-internal.js

@@ -1205,8 +1205,12 @@ function mountInternalSurfaces(app) {
   // GET /sky/mine, with the room inside it as the list drawer. The old ambient
   // page at `sky` (task 1004105) is gone; its URL 301s to /thinking below, so it
   // leaves this regex — one URL cannot be two tiers, and a redirect is not a page.
+  // task 1004321 (BV2.TW10): `tweak-editor`, Tweak Mode's editor, the artist's
+  // own room beside the studio, on the studio's tier. Its read (GET
+  // /copy-desk/pages/:pageId/draft) is any-builder like the .docx download, and
+  // every write is the page claim's holder only, checked server-side.
   const SIGNEDIN_BUILDERS_PAGE_RE =
-    /^\/builders\/(?:work|settings|atlas|modules|goals|goal-map|roadmap|copy-desk|studio|ideas|thinking|collab|task|idea|primer(?:\.md)?|diagrams)(?:\.html)?\/?$/;
+    /^\/builders\/(?:work|settings|atlas|modules|goals|goal-map|roadmap|copy-desk|studio|tweak-editor|ideas|thinking|collab|task|idea|primer(?:\.md)?|diagrams)(?:\.html)?\/?$/;
   // The diagram image assets under /builders/diagrams/ ride the same tier as the
   // page that embeds them.
   const SIGNEDIN_BUILDERS_PREFIX_RE = /^\/builders\/diagrams\//;

package/src/module-api.js

@@ -71,7 +71,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // there. scripts/gds/bump-version.js still rewrites the literal below; it appends
 // the entry to that file. Look for a version's history there, not here.
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.1061'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.1063'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

package/tests/copy_desk_page_docx.mjs

@@ -0,0 +1,279 @@
+// tests/copy_desk_page_docx.mjs — download a page as .docx, edit it the way
+// Word stores an edit, and upload it back into the draft, the WHOLE path (task
+// 1004320 / BV2.TW09, ADR 0341 D12).
+//
+// The done-when: a round trip with edits lands those edits in the draft, and a
+// structure-changing upload is refused by name.
+//
+// Driven through the real copy-desk routes (with the real raw-body parser and
+// its cap), the real lifecycle port (the page claim, updateHeldTaskDescription,
+// submitPageTweak, createTask) and the real page reads, against the shared
+// stateful fake ledger (tests/fixtures/page-ledger.mjs). The reading is a file
+// on disk, read through the real page-data.js. The file is edited by the
+// Word-shaped fixture, which re-packs it with its own zip writer.
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { makeRunner } from './helpers.mjs';
+import { installPageLedger } from './fixtures/page-ledger.mjs';
+import { resave, typeInto, wordRuns, lineParagraph } from '../modules/copy-desk/tests/fixtures/word-docx.mjs';
+
+process.env.NODE_ENV = 'test';
+const require = createRequire(import.meta.url);
+const F = require('../modules/copy-desk/tests/fixtures/page-tweak.cjs');
+const pages = require('../modules/copy-desk/pages.js');
+const docx = require('../modules/copy-desk/docx.js');
+const api = require('../src/module-api.js');
+
+const { db } = installPageLedger(api, {
+  builders: [
+    { id: '7', github_login: 'alice', display_name: 'Alice', preferred_disciplines: ['artist'] },
+    { id: '8', github_login: 'bob', display_name: 'Bob', preferred_disciplines: ['artist'] },
+  ],
+});
+const ALICE = '7';
+const BOB = '8';
+
+api.requireBuilder = (req, res, next) => {
+  req.builder = { id: String(req.headers['x-builder'] || ALICE), rank: 'metic' };
+  next();
+};
+
+const seams = require('../src/module-seams.js');
+const lifecyclePort = require('../modules/lifecycle/lifecycle.js');
+if (!seams.hasProvider('lifecycle')) seams.registerProvider('lifecycle', lifecyclePort);
+
+const pageData = require('../modules/copy-desk/page-data.js');
+const express = require('express');
+const { attachFail } = require('../src/bongos/middleware/error-envelope.js');
+const buildRouter = require('../modules/copy-desk/routes/copy-desk.js');
+
+const app = express();
+app.use(express.json());
+app.use(attachFail);
+app.use(buildRouter());
+const server = await new Promise((resolve) => { const s = app.listen(0, '127.0.0.1', () => resolve(s)); });
+const base = `http://127.0.0.1:${server.address().port}`;
+
+async function call(method, p, builder, body = {}) {
+  const r = await fetch(base + p, { method, headers: { 'content-type': 'application/json', 'x-builder': builder }, body: method === 'GET' ? undefined : JSON.stringify(body) });
+  return { status: r.status, body: await r.json() };
+}
+async function getDocx(p, builder) {
+  const r = await fetch(base + p, { headers: { 'x-builder': builder } });
+  return { status: r.status, headers: r.headers, buf: Buffer.from(await r.arrayBuffer()) };
+}
+async function putDocx(p, builder, buf, type = docx.DOCX_MIME) {
+  const r = await fetch(base + p, { method: 'POST', headers: { 'content-type': type, 'x-builder': builder }, body: buf });
+  return { status: r.status, body: await r.json() };
+}
+const errCode = (b) => (b && b.error && b.error.code) || null;
+const errDetail = (b) => (b && b.error && b.error.details) || {};
+
+const L = (key, section, text, placement, row) => ({ key, section, text, placement, ...(row || {}) });
+const STUDIO_LINES = [
+  L('L0001', 'top bar', 'Studio', 'shared', { file: 'modules/hall-ui/public/shell.js', line: 40, string_id: 'sh0001' }),
+  L('L0002', 'top bar', 'Ctrl K', 'shared'),
+  L('L0003', 'greeting', 'Welcome back', 'placed', { file: 'modules/hall-ui/public/studio.html', line: 12, string_id: 'st0003' }),
+  L('L0004', 'greeting', '{…} pages tweaked', 'placed', { file: 'modules/hall-ui/public/studio.js', line: 88, string_id: 'st0004' }),
+  L('L0005', 'greeting', 'Your desk is quiet today', 'unplaced'),
+  L('L0006', 'footer', 'Resume where you left off', 'placed', { file: 'modules/hall-ui/public/studio.html', line: 90, string_id: 'st0006' }),
+];
+const INDEX_LINES = [
+  L('L0001', 'hero', 'Build here', 'placed', { file: 'modules/public-landing/public/index.html', line: 3, string_id: 'ix0001' }),
+];
+const readingsWith = (studioHash) => ({
+  schema: 1,
+  pages: [
+    { id: 'builders:studio', reading_hash: studioHash, lines: STUDIO_LINES },
+    { id: 'landing:index', reading_hash: 'index-h1', lines: INDEX_LINES },
+  ],
+});
+
+const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'page-docx-'));
+fs.mkdirSync(path.join(tmp, 'docs'), { recursive: true });
+fs.writeFileSync(path.join(tmp, 'docs/page-inventory.json'), JSON.stringify(F.INVENTORY));
+function writeReadings(r) {
+  fs.writeFileSync(path.join(tmp, 'docs/page-readings.json'), JSON.stringify(r));
+  pageData._setRoot(tmp); // drop the (mtime, size) cache
+}
+
+const { test, summary } = makeRunner();
+const STUDIO = '/copy-desk/pages/builders:studio';
+const INDEX = '/copy-desk/pages/landing:index';
+const studioTask = () => db.tasks.find((t) => t.source_ref === 'page-tweak/builders:studio/r1');
+const draftLines = () => pages.parseDraftBlock(studioTask().description).draft.lines.map((l) => [l.key, l.before, l.after]);
+let downloaded = null;
+
+try {
+  writeReadings(readingsWith('studio-h1'));
+
+  await test('the download works before anyone claims the page: the reading, as a Word file', async () => {
+    const r = await getDocx(`${INDEX}/draft.docx`, BOB);
+    assert.equal(r.status, 200);
+    assert.equal(r.headers.get('content-type'), docx.DOCX_MIME);
+    assert.equal(r.headers.get('content-disposition'), 'attachment; filename="tweak-landing-index.docx"');
+    const u = docx.readUpload(r.buf);
+    assert.equal(u.ok, true);
+    assert.equal(u.page_id, 'landing:index');
+    assert.deepEqual([...u.baseline], [['L0001', 'Build here']]);
+  });
+
+  await test('the download is built from the reading plus the artist\'s current draft', async () => {
+    assert.equal((await call('POST', `${STUDIO}/claim`, ALICE)).status, 201);
+    const saved = await call('PUT', `${STUDIO}/draft`, ALICE, { reading_hash: 'studio-h1', lines: [{ key: 'L0003', after: 'Welcome home' }] });
+    assert.equal(saved.body.outcome, 'saved');
+    const r = await getDocx(`${STUDIO}/draft.docx`, ALICE);
+    assert.equal(r.status, 200);
+    downloaded = r.buf;
+    const u = docx.readUpload(r.buf);
+    assert.deepEqual([u.page_id, u.reading_hash], ['builders:studio', 'studio-h1']);
+    assert.equal(u.baseline.get('L0003'), 'Welcome home', 'the draft rewrite, not the page text');
+    assert.equal(u.baseline.get('L0006'), 'Resume where you left off');
+    assert.deepEqual(u.paragraphs.filter((p) => p.tags.length).map((p) => p.tags[0]), STUDIO_LINES.map((l) => l.key));
+  });
+
+  await test('a round trip with edits (Word\'s split runs and smart quotes) lands those edits in the draft', async () => {
+    const writes = db.writes;
+    const edited = resave(downloaded, {
+      document: (xml) => typeInto(typeInto(xml, 'L0006', wordRuns(['Pick ', 'up where ', 'you’re ', 'at'])),
+        'L0004', wordRuns(['{…} ', 'pages rewritten'])),
+    });
+    const r = await putDocx(`${STUDIO}/draft.docx`, ALICE, edited);
+    assert.equal(r.status, 200, JSON.stringify(r.body));
+    assert.equal(r.body.outcome, 'saved');
+    assert.deepEqual(r.body.merge, { mode: 'tag', baseline: true, from_file: ['L0004', 'L0006'], kept_from_draft: ['L0003'] });
+    assert.deepEqual(r.body.counter, { changed: 3, total: 6 });
+    assert.deepEqual(draftLines(), [
+      ['L0003', 'Welcome back', 'Welcome home'],
+      ['L0004', '{…} pages tweaked', '{…} pages rewritten'],
+      ['L0006', 'Resume where you left off', 'Pick up where you\'re at'],
+    ]);
+    // Into the DRAFT and nowhere else: one write, the round still writing,
+    // no frozen batch, one draft block, and the reading on disk untouched.
+    assert.equal(db.writes, writes + 1);
+    assert.equal(studioTask().status, 'active');
+    assert.equal(pages.blockPresence(studioTask().description).batch, false);
+    assert.equal((studioTask().description.match(/```page-tweak-draft/g) || []).length, 1);
+    assert.deepEqual(JSON.parse(fs.readFileSync(path.join(tmp, 'docs/page-readings.json'), 'utf8')), readingsWith('studio-h1'));
+  });
+
+  await test('the same upload again writes nothing', async () => {
+    const writes = db.writes;
+    const stamp = studioTask().updated_at;
+    const edited = resave(downloaded, {
+      document: (xml) => typeInto(typeInto(xml, 'L0006', wordRuns(['Pick ', 'up where ', 'you’re ', 'at'])),
+        'L0004', wordRuns(['{…} ', 'pages rewritten'])),
+    });
+    const r = await putDocx(`${STUDIO}/draft.docx`, ALICE, edited);
+    assert.equal(r.body.outcome, 'unchanged');
+    assert.equal(db.writes, writes);
+    assert.equal(studioTask().updated_at, stamp);
+  });
+
+  await test('a rewrite made in the studio after the download survives an upload of the older file', async () => {
+    // The artist keeps working in the studio (a whole-draft save), then
+    // uploads the file they downloaded earlier with one more Word edit.
+    const saved = await call('PUT', `${STUDIO}/draft`, ALICE, { reading_hash: 'studio-h1', lines: [{ key: 'L0003', after: 'Hello again' }, { key: 'L0005', after: 'Nothing is waiting' }] });
+    assert.equal(saved.body.outcome, 'saved');
+    const edited = resave(downloaded, { document: (xml) => typeInto(xml, 'L0001', wordRuns(['Your ', 'studio'])) });
+    const r = await putDocx(`${STUDIO}/draft.docx`, ALICE, edited);
+    assert.equal(r.status, 200, JSON.stringify(r.body));
+    assert.deepEqual(r.body.merge.from_file, ['L0001']);
+    assert.deepEqual(draftLines().map(([k, , a]) => [k, a]), [
+      ['L0001', 'Your studio'],
+      ['L0003', 'Hello again'],
+      ['L0005', 'Nothing is waiting'],
+    ]);
+  });
+
+  await test('a structure-changing upload is refused by name, and nothing is saved', async () => {
+    const writes = db.writes;
+    const buf = resave(downloaded, {
+      document: (xml) => {
+        const p = lineParagraph(xml, 'L0003');
+        return xml.replace(lineParagraph(xml, 'L0005'), '').replace(p, () => `${p}<w:p><w:r><w:t>An extra thought</w:t></w:r></w:p>`);
+      },
+    });
+    const r = await putDocx(`${STUDIO}/draft.docx`, ALICE, buf);
+    assert.equal(r.status, 409);
+    assert.equal(errCode(r.body), 'structure_changed');
+    assert.deepEqual(errDetail(r.body).moved, [
+      { change: 'added', key: null, section: 'greeting', first_words: 'An extra thought' },
+      { change: 'dropped', key: 'L0005', section: 'greeting', first_words: 'Your desk is quiet today' },
+    ]);
+    assert.match(errDetail(r.body).what_this_means, /added, removed or moved/);
+    assert.equal(db.writes, writes);
+  });
+
+  await test('another page\'s file is wrong_page; a file from an older reading is reading_moved', async () => {
+    assert.equal((await call('POST', `${INDEX}/claim`, BOB)).status, 201);
+    const wrong = await putDocx(`${INDEX}/draft.docx`, BOB, downloaded);
+    assert.equal(wrong.status, 409);
+    assert.equal(errCode(wrong.body), 'wrong_page');
+    assert.equal(errDetail(wrong.body).file_page_id, 'builders:studio');
+
+    writeReadings(readingsWith('studio-h2'));
+    const moved = await putDocx(`${STUDIO}/draft.docx`, ALICE, downloaded);
+    assert.equal(moved.status, 409);
+    assert.equal(errCode(moved.body), 'reading_moved');
+    assert.deepEqual([errDetail(moved.body).reading_hash, errDetail(moved.body).file_reading_hash], ['studio-h2', 'studio-h1']);
+    writeReadings(readingsWith('studio-h1'));
+  });
+
+  await test('only the holder may upload: page_not_held names the holder', async () => {
+    const r = await putDocx(`${STUDIO}/draft.docx`, BOB, downloaded);
+    assert.equal(r.status, 409);
+    assert.equal(errCode(r.body), 'page_not_held');
+    assert.deepEqual(errDetail(r.body).holder, { id: ALICE, login: 'alice', name: 'Alice' });
+  });
+
+  await test('the upload is user input: anything not a .docx is refused, and the size is capped', async () => {
+    const writes = db.writes;
+    const json = await call('POST', `${STUDIO}/draft.docx`, ALICE, { lines: [] });
+    assert.equal(json.status, 415);
+    assert.equal(errCode(json.body), 'not_a_docx');
+    const text = await putDocx(`${STUDIO}/draft.docx`, ALICE, Buffer.from('hello'), 'text/plain');
+    assert.equal(errCode(text.body), 'not_a_docx');
+    const junk = await putDocx(`${STUDIO}/draft.docx`, ALICE, Buffer.from('not a zip at all'));
+    assert.equal(junk.status, 415);
+    assert.equal(errCode(junk.body), 'not_a_docx');
+    const zip = await putDocx(`${STUDIO}/draft.docx`, ALICE, docx.writeZip([{ name: 'notes.txt', data: 'hi' }]), 'application/zip');
+    assert.equal(errCode(zip.body), 'not_a_docx');
+    const big = await putDocx(`${STUDIO}/draft.docx`, ALICE, Buffer.alloc(docx.MAX_UPLOAD_BYTES + 1024, 7));
+    assert.equal(big.status, 413);
+    assert.equal(errCode(big.body), 'upload_too_large');
+    assert.equal(db.writes, writes);
+  });
+
+  await test('no round is no_open_round; after submit the draft is frozen, so an upload is page_in_flight', async () => {
+    const indexFile = (await getDocx(`${INDEX}/draft.docx`, BOB)).buf;
+    // Bob holds index; a page nobody opened a round on has nowhere to land.
+    const inv = F.INVENTORY.pages.find((p) => p.id !== 'builders:studio' && p.id !== 'landing:index');
+    assert.ok(inv, 'the fixture inventory has a page with no round');
+    const readings = readingsWith('studio-h1');
+    readings.pages.push({ id: inv.id, reading_hash: 'x-h1', lines: [L('L0001', 'hero', 'Hi', 'placed', { file: 'f', line: 1, string_id: 's' })] });
+    writeReadings(readings);
+    const other = (await getDocx(`/copy-desk/pages/${inv.id}/draft.docx`, BOB)).buf;
+    const none = await putDocx(`/copy-desk/pages/${inv.id}/draft.docx`, BOB, other);
+    assert.equal(errCode(none.body), 'no_open_round');
+    writeReadings(readingsWith('studio-h1'));
+    const edited = resave(indexFile, { document: (xml) => typeInto(xml, 'L0001', wordRuns(['Build ', 'it here'])) });
+    assert.equal((await putDocx(`${INDEX}/draft.docx`, BOB, edited)).body.outcome, 'saved');
+    assert.equal((await call('POST', `${INDEX}/submit`, BOB)).body.outcome, 'submitted');
+    const after = await putDocx(`${INDEX}/draft.docx`, BOB, edited);
+    assert.equal(after.status, 409);
+    assert.equal(errCode(after.body), 'page_in_flight');
+    // The submitted batch carries the Word edit, with its target from the reading.
+    const t = db.tasks.find((x) => x.source_ref === 'page-tweak/landing:index/r1');
+    assert.deepEqual(pages.parseBatchBlock(t.description).batch.lines.map((l) => [l.key, l.file, l.before, l.after]),
+      [['L0001', 'modules/public-landing/public/index.html', 'Build here', 'Build it here']]);
+  });
+} finally {
+  server.close();
+  pageData._setRoot(null);
+}
+summary();

package/tests/copy_desk_page_editor.mjs

@@ -0,0 +1,181 @@
+// tests/copy_desk_page_editor.mjs — the read the tweak editor opens on,
+// GET /copy-desk/pages/:pageId/draft, the WHOLE path (task 1004321 / BV2.TW10,
+// ADR 0341 D4).
+//
+// The done-when's middle: an artist rewrites a page, closes the tab, and comes
+// back to the draft. So the read must give back every line of the page in page
+// order with its margin note, say whether the caller holds the round, and hand
+// back exactly the draft the autosave stored, and never a draft saved on
+// another reading (its keys may name other lines).
+//
+// Driven through the real copy-desk routes, the real lifecycle port (the page
+// claim, updateHeldTaskDescription, submitPageTweak) and the real page reads,
+// against the shared stateful fake ledger (tests/fixtures/page-ledger.mjs).
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { makeRunner } from './helpers.mjs';
+import { installPageLedger } from './fixtures/page-ledger.mjs';
+
+process.env.NODE_ENV = 'test';
+const require = createRequire(import.meta.url);
+const F = require('../modules/copy-desk/tests/fixtures/page-tweak.cjs');
+const pageStatus = require('../modules/copy-desk/page-status.js');
+const api = require('../src/module-api.js');
+
+installPageLedger(api, {
+  builders: [
+    { id: '7', github_login: 'alice', display_name: 'Alice', preferred_disciplines: ['artist'] },
+    { id: '8', github_login: 'bob', display_name: 'Bob', preferred_disciplines: ['artist'] },
+  ],
+});
+const ALICE = '7';
+const BOB = '8';
+
+api.requireBuilder = (req, res, next) => {
+  req.builder = { id: String(req.headers['x-builder'] || ALICE), rank: 'metic' };
+  next();
+};
+
+const seams = require('../src/module-seams.js');
+const lifecyclePort = require('../modules/lifecycle/lifecycle.js');
+if (!seams.hasProvider('lifecycle')) seams.registerProvider('lifecycle', lifecyclePort);
+
+const pageData = require('../modules/copy-desk/page-data.js');
+const express = require('express');
+const { attachFail } = require('../src/bongos/middleware/error-envelope.js');
+const buildRouter = require('../modules/copy-desk/routes/copy-desk.js');
+
+const app = express();
+app.use(express.json());
+app.use(attachFail);
+app.use(buildRouter());
+const server = await new Promise((resolve) => { const s = app.listen(0, '127.0.0.1', () => resolve(s)); });
+const base = `http://127.0.0.1:${server.address().port}`;
+
+async function call(method, p, builder, body = {}) {
+  const r = await fetch(base + p, { method, headers: { 'content-type': 'application/json', 'x-builder': builder }, body: method === 'GET' ? undefined : JSON.stringify(body) });
+  return { status: r.status, body: await r.json() };
+}
+const errCode = (b) => (b && b.error && b.error.code) || null;
+
+const L = (key, section, text, placement, row) => ({ key, section, text, placement, ...(row || {}) });
+const STUDIO_LINES = [
+  L('L0001', 'top bar', 'Studio', 'shared', { file: 'modules/hall-ui/public/shell.js', line: 40, string_id: 'sh0001' }),
+  L('L0002', 'top bar', 'Ctrl K', 'shared'),
+  L('L0003', 'greeting', 'Welcome back', 'placed', { file: 'modules/hall-ui/public/studio.html', line: 12, string_id: 'st0003' }),
+  L('L0004', 'greeting', 'Your desk is quiet today', 'unplaced'),
+  L('L0005', 'footer', 'Resume where you left off', 'placed', { file: 'modules/hall-ui/public/studio.html', line: 90, string_id: 'st0005' }),
+];
+const readingsWith = (studioHash, lines = STUDIO_LINES) => ({
+  schema: 1,
+  pages: [{ id: 'builders:studio', reading_hash: studioHash, lines }],
+});
+
+const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'page-editor-'));
+fs.mkdirSync(path.join(tmp, 'docs'), { recursive: true });
+fs.writeFileSync(path.join(tmp, 'docs/page-inventory.json'), JSON.stringify(F.INVENTORY));
+function writeReadings(r) {
+  fs.writeFileSync(path.join(tmp, 'docs/page-readings.json'), JSON.stringify(r));
+  pageData._setRoot(tmp); // drop the (mtime, size) cache
+}
+
+const { test, summary } = makeRunner();
+const STUDIO = '/copy-desk/pages/builders:studio';
+
+try {
+  writeReadings(readingsWith('studio-h1'));
+
+  await test('before anyone claims: every line in page order, with its margin note, and no round', async () => {
+    const r = await call('GET', `${STUDIO}/draft`, ALICE);
+    assert.equal(r.status, 200, JSON.stringify(r.body));
+    assert.equal(r.body.page.title, 'Studio');
+    assert.equal(r.body.page.surface_word, 'builders hall');
+    assert.equal(r.body.reading.reading_hash, 'studio-h1');
+    assert.deepEqual(r.body.reading.lines.map((l) => [l.key, l.section, l.text, l.note]), [
+      ['L0001', 'top bar', 'Studio', 'shared'],
+      // Shared shell text with no registry row cannot be applied mechanically,
+      // so it goes to an engineer at submit, and the note says so.
+      ['L0002', 'top bar', 'Ctrl K', 'engineer'],
+      ['L0003', 'greeting', 'Welcome back', null],
+      ['L0004', 'greeting', 'Your desk is quiet today', 'engineer'],
+      ['L0005', 'footer', 'Resume where you left off', null],
+    ]);
+    assert.deepEqual(r.body.notes, { shared: 'changes this on every page', engineer: 'goes to an engineer' });
+    assert.equal(r.body.round, null);
+    assert.equal(r.body.draft, null);
+    assert.deepEqual(r.body.counter, { changed: 0, total: 5 });
+    // The read never exposes where a line lives in the code.
+    assert.equal(r.body.reading.lines.some((l) => 'file' in l || 'string_id' in l), false);
+  });
+
+  await test('rewrite, close the tab, come back: the read hands back the saved draft, held by you', async () => {
+    assert.equal((await call('POST', `${STUDIO}/claim`, ALICE)).status, 201);
+    const saved = await call('PUT', `${STUDIO}/draft`, ALICE, {
+      reading_hash: 'studio-h1',
+      lines: [{ key: 'L0003', after: 'Welcome home' }, { key: 'L0001', after: 'The studio' }],
+    });
+    assert.equal(saved.body.outcome, 'saved');
+    const back = await call('GET', `${STUDIO}/draft`, ALICE);
+    assert.equal(back.status, 200);
+    assert.equal(back.body.round.state, 'writing');
+    assert.equal(back.body.round.held_by_you, true);
+    assert.equal(back.body.round.claim.path, '/copy-desk/pages/builders:studio/claim');
+    assert.deepEqual(back.body.draft.lines, [{ key: 'L0001', after: 'The studio' }, { key: 'L0003', after: 'Welcome home' }]);
+    assert.equal(back.body.draft.saved_at, saved.body.draft.saved_at);
+    assert.deepEqual(back.body.counter, { changed: 2, total: 5 });
+  });
+
+  await test('another artist sees the round held by its writer, not by them', async () => {
+    const r = await call('GET', `${STUDIO}/draft`, BOB);
+    assert.equal(r.body.round.held_by_you, false);
+    assert.deepEqual(r.body.round.holder, { id: ALICE, login: 'alice' });
+  });
+
+  await test('a draft saved on an older reading is reported, never laid over the new lines', async () => {
+    writeReadings(readingsWith('studio-h2'));
+    const r = await call('GET', `${STUDIO}/draft`, ALICE);
+    assert.equal(r.body.draft, null);
+    assert.equal(r.body.draft_on_older_reading, true);
+    assert.deepEqual(r.body.counter, { changed: 0, total: 5 });
+    writeReadings(readingsWith('studio-h1'));
+  });
+
+  await test('after submit the round reads submitted and nobody holds it', async () => {
+    assert.equal((await call('POST', `${STUDIO}/submit`, ALICE)).body.outcome, 'submitted');
+    const r = await call('GET', `${STUDIO}/draft`, ALICE);
+    assert.equal(r.body.round.state, 'submitted');
+    assert.equal(r.body.round.held_by_you, false);
+    assert.equal(r.body.round.holder, null);
+  });
+
+  await test('an unknown page is unknown_page, and a page with no reading is page_unread', async () => {
+    const r = await call('GET', '/copy-desk/pages/landing:nowhere/draft', ALICE);
+    assert.equal(r.status, 404);
+    assert.equal(errCode(r.body), 'unknown_page');
+    const u = await call('GET', '/copy-desk/pages/landing:index/draft', ALICE);
+    assert.equal(u.status, 503);
+    assert.equal(errCode(u.body), 'page_unread');
+  });
+
+  await test('composeEditor keeps only draft lines the reading still has', () => {
+    const out = pageStatus.composeEditor({
+      page: { id: 'builders:studio', title: 'Studio', surface: 'builders' },
+      readingPage: { reading_hash: 'h', lines: [STUDIO_LINES[2]] },
+      round: { id: 9, status: 'active', holder_id: 7, holder_login: 'alice', description: '```page-tweak-draft\n' + JSON.stringify({ schema: 1, page_id: 'builders:studio', reading_hash: 'h', saved_at: 'x', lines: [
+        { key: 'L0003', section: 'greeting', before: 'Welcome back', after: 'Hi', placement: 'placed' },
+        { key: 'L0099', section: 'gone', before: 'Old', after: 'New', placement: 'placed' },
+      ] }) + '\n```\n' },
+      builderId: 7,
+    });
+    assert.deepEqual(out.draft.lines, [{ key: 'L0003', after: 'Hi' }]);
+    assert.equal(out.round.held_by_you, true);
+  });
+} finally {
+  server.close();
+  pageData._setRoot(null);
+}
+summary();

package/tests/fitness.mjs

@@ -922,9 +922,14 @@ test('write-route validation check actually CATCHES an unvalidated write route (
   assert.ok(/POST \/widgets/.test(flagged[0]), 'the offending route is named');
 });
 
-test('write-route validation exemptions are the known dynamic-key prefs routes only', () => {
+test('write-route validation exemptions are the known dynamic-key prefs routes, plus the one raw-file upload', () => {
+  // The .docx upload (task 1004320) has no JSON body to hold a field schema: its
+  // body is the file's bytes, capped by the route's parser and read by
+  // docx.readUpload. Named here so a second raw-body exemption is a reviewed diff.
+  const RAW_FILE_UPLOADS = ['POST /copy-desk/pages/:pageId/draft.docx'];
   const exempt = [...fitness.WRITE_VALIDATION_EXEMPT];
-  assert.ok(exempt.length >= 1 && exempt.every((e) => e.startsWith('PATCH /me/')), 'exemptions are all /me/* prefs patches: ' + exempt.join(', '));
+  assert.ok(exempt.length >= 1 && exempt.every((e) => e.startsWith('PATCH /me/') || RAW_FILE_UPLOADS.includes(e)),
+    'exemptions are all /me/* prefs patches or a named raw-file upload: ' + exempt.join(', '));
 });
 
 test('identity gate strips comments on CRLF checkouts too (task 1002428)', () => {

package/tests/hall_audit.mjs

@@ -424,6 +424,11 @@ const LITERAL_EXEMPT = {
   'thinking.css': 'the sky\'s own sheet is its token tier (task 1004231, ADR 0331 — the design of record)',
   'sky-interaction.js': 'the sky\'s hover card writes the template\'s ring colour inline (task 1004231)',
   'sky-panel.js': 'the sky\'s panel writes the template\'s dead-bar colour inline (task 1004231)',
+  // The tweak editor (task 1004321 / BV2.TW10): docs/design/mocks/tweak-mode/
+  // Editor.dc.html is the owner-approved master design, built 1:1: the night
+  // studio, the glass bar, and a sheet of PAPER that stays paper in both modes,
+  // so its palette cannot be the hall's mode-flipping tier. The sky precedent.
+  'tweak-editor.css': 'the tweak editor\'s stage is the artboard\'s own palette (task 1004321, the pixel contract: paper in both modes)',
 };
 const COLOUR_PROPS = 'color|background|background-color|border|border-color|border-top-color|border-bottom-color|fill|stroke|outline|outline-color|box-shadow|text-shadow';
 const colourLiteralRe = () =>

package/tests/hall_page_gate_map.mjs

@@ -62,6 +62,9 @@ const ORACLE = {
   // whole gate, and its two reads (GET /tasks, GET /copy-desk/queue) already gate
   // themselves server-side.
   '/builders/studio': 'requireBuilderPage',
+  // task 1004321 (BV2.TW10): the tweak editor, on the studio's own tier. Its read
+  // is any-builder like the .docx download; every write is the page holder's only.
+  '/builders/tweak-editor': 'requireBuilderPage',
   '/builders/ideas': 'requireBuilderPage',
   // THE ROOM (task 1004098 / BV2.R03) — a builder's own idea trail. Sign-in and
   // no rank floor, the tier /ideas sits on: there is no permission gate on