@bongos/core 1.19.1062 → 1.19.1064

package/scripts/gds/strand-watch.js

@@ -38,6 +38,7 @@
 // Exit codes: 0 always on --line (fail-open). Otherwise 0 clean, 1 strands found, 2 undetermined.
 
 const { apiCall, arg, hasFlag } = require('./cli-lib');
+const tweakHold = require('../../modules/lifecycle/page-tweak-hold.js');
 
 // ---- thresholds -------------------------------------------------------------
 // Reasoned, not magic. Written down because a future reader will want to retune them.
@@ -132,6 +133,31 @@ function rankStrands(strands) {
   });
 }
 
+// ---- the held pass (task 1004322, ADR 0341 D7) --------------------------------
+//
+// A page tweak whose grade PASSED waits at `completed` for its artist on purpose:
+// the artist approves the applied page before it lands. It is not a strand and not
+// a failed grade, and calling it one would send someone to /grade-recover a task
+// nobody should touch. The task list carries no grade, so each completed page
+// tweak's grade is read on its own (there are a handful at most; the read is
+// bounded anyway). A read that FAILS leaves the task to the ordinary
+// classification: an unknown must stay loud, never be explained away as a hold.
+const HOLD_READ_LIMIT = 25;
+
+async function heldPageTweaks(tasks, { call, withTimeout }) {
+  const candidates = tasks.filter((t) => t && t.status === 'completed' && tweakHold.isPageTweak(t) && safeId(t.id)).slice(0, HOLD_READ_LIMIT);
+  const held = new Set();
+  await Promise.all(candidates.map(async (t) => {
+    try {
+      const res = await withTimeout(call('GET', `/api/bongos/tasks/${safeId(t.id)}?include=grade`), 'page-tweak grade');
+      const body = res && (res.data || res);
+      const grade = body && body.grade;
+      if (tweakHold.isHeldForArtist(t, grade ? grade.passed : null)) held.add(String(t.id));
+    } catch { /* unknown: classified as usual */ }
+  }));
+  return held;
+}
+
 // ---- fetch ------------------------------------------------------------------
 
 async function check({ nowMs = Date.now(), timeoutMs = DEFAULT_TIMEOUT_MS, confirmedStaleMs, completedStaleMs, call = apiCall } = {}) {
@@ -157,14 +183,23 @@ async function check({ nowMs = Date.now(), timeoutMs = DEFAULT_TIMEOUT_MS, confi
 
   const strands = [];
   const truncated = [];
+  const waiting = [];
+  const completed = (pages.find((p) => p.status === 'completed') || { tasks: [] }).tasks;
+  const held = await heldPageTweaks(completed, { call, withTimeout });
   for (const { status, tasks } of pages) {
     if (tasks.length >= PAGE_LIMIT) truncated.push(status);
     for (const t of tasks) {
+      if (status === 'completed' && held.has(String(t.id))) {
+        const updated = Date.parse(t.updated_at || '');
+        const ageMs = Number.isFinite(updated) ? nowMs - updated : NaN;
+        waiting.push({ id: safeId(t.id), status, ageMs, age: humanAge(ageMs), shape: tweakHold.HOLD_STATE });
+        continue;
+      }
       const s = classifyStrand(t, { nowMs, confirmedStaleMs, completedStaleMs });
       if (s) strands.push(s);
     }
   }
-  return { undetermined: false, ok: strands.length === 0 && !truncated.length, strands: rankStrands(strands), truncated };
+  return { undetermined: false, ok: strands.length === 0 && !truncated.length, strands: rankStrands(strands), truncated, waiting };
 }
 
 // ---- rendering --------------------------------------------------------------
@@ -218,6 +253,11 @@ function report(r) {
     console.log(`  ! coverage capped: the ${r.truncated.join(' and ')} queue(s) returned a full ${PAGE_LIMIT}-row page,`);
     console.log('    so strands older than the cutoff are NOT listed below.');
   }
+  // task 1004322: named, and kept apart from the strands — nobody should recover these.
+  const waiting = Array.isArray(r.waiting) ? r.waiting : [];
+  for (const w of waiting) {
+    console.log(`  task ${w.id}  waiting for the artist (${w.age}) — a page tweak whose grade passed; not a strand, leave it`);
+  }
   if (r.ok) {
     console.log('  ✓ none — nothing parked at completed or confirmed past its threshold.');
     console.log('');

package/scripts/gds/task.js

@@ -13,6 +13,8 @@
 //   bongos task show <id> [--json]
 //   bongos task visual <id> <image> [--alt "caption"]   attach/replace the ship-time visual
 //   bongos task visual <id> --remove                    take it back off
+//   bongos task visual <id> <image> --slot <name>       attach/replace a NAMED visual (task 1004322)
+//   bongos task visual <id> --slot <name> --remove      take a named one back off
 //
 // Task CREATION is Archon-gated SERVER-SIDE (creating work shapes scope, ADR 0016). This
 // CLI adds no authority — a lower rank gets a clear 403 message pointing at idea capture.
@@ -84,6 +86,7 @@ function usage() {
   console.error('  bongos task show <id> [--json]');
   console.error('  bongos task visual <id> <image> [--alt "caption"]   attach or replace the ship-time visual');
   console.error('  bongos task visual <id> --remove                    remove it again');
+  console.error('  bongos task visual <id> <image> --slot <name>       attach or replace a named visual (e.g. after-phone-dark)');
   console.error(`\n  kinds: ${VALID_KINDS.join(' | ')}`);
   console.error(`  disciplines: ${VALID_DISCIPLINES.join(' | ')}`);
 }
@@ -174,6 +177,21 @@ async function cmdVisual(args) {
   }
   const api = await cliClient();
 
+  // task 1004322: --slot names the visual (lifecycle_013). Validated here with the
+  // server's own rule, so a bad name costs a retyped command, not an upload.
+  const slot = arg('--slot', args) || null;
+  if (slot !== null && !taskVisuals.isSafeSlot(slot)) {
+    console.error(`--slot "${slot}" is not a slot name: lowercase words joined by dashes, such as ${taskVisuals.TWEAK_RENDER_SLOTS[0]}.`);
+    process.exit(2);
+  }
+  if (slot && hasFlag('--remove', args)) {
+    const r = await api.tasks.deleteTasksIdVisualsSlot({ id, slot });
+    if (r.status === 404) { console.error(`task #${id} not found.`); process.exit(1); }
+    if (!r.ok) { console.error(`visual remove failed (${r.status}):`, r.data); process.exit(1); }
+    console.log(`✓ Task #${id} no longer carries the "${slot}" visual.`);
+    return;
+  }
+
   if (hasFlag('--remove', args)) {
     const r = await api.tasks.deleteTasksIdVisual({ id });
     if (r.status === 404) { console.error(`task #${id} not found.`); process.exit(1); }
@@ -199,14 +217,14 @@ async function cmdVisual(args) {
   }
 
   const alt = arg('--alt', args) || '';
-  const r = await api.tasks.postTasksIdVisual({
-    id,
-    body: { image_b64: visual.buf.toString('base64'), content_type: visual.contentType, ...(alt ? { alt } : {}) },
-  });
+  const body = { image_b64: visual.buf.toString('base64'), content_type: visual.contentType, ...(alt ? { alt } : {}) };
+  const r = slot
+    ? await api.tasks.postTasksIdVisualsSlot({ id, slot, body })
+    : await api.tasks.postTasksIdVisual({ id, body });
   if (r.status === 404) { console.error(`task #${id} not found.`); process.exit(1); }
   if (r.status === 403) { console.error(`Only task #${id}'s claim holder (or an Archon) may attach its visual.`); process.exit(1); }
   if (!r.ok) { console.error(`visual upload failed (${r.status}):`, r.data); process.exit(1); }
-  console.log(`✓ Task #${id} now carries a visual (${Math.round(visual.buf.length / 1024)} KB).`);
+  console.log(`✓ Task #${id} now carries ${slot ? `the "${slot}" visual` : 'a visual'} (${Math.round(visual.buf.length / 1024)} KB).`);
   console.log('  It renders wherever this task\'s value summary does.');
 }
 

package/scripts/gds/tweak-renders.js

@@ -0,0 +1,200 @@
+#!/usr/bin/env node
+'use strict';
+//
+// scripts/gds/tweak-renders.js — the eight renders of a page tweak, shot and
+// attached (task 1004322 / BV2.TW11; ADR 0341 D7 and its builder pick 9).
+//
+// WHY. The artist approves the APPLIED PAGE, not a diff and not a page built from
+// the batch: the Approval queue (TW12) shows images of the applied branch, which
+// is what keeps ADR 0233's "nothing renders a task description as product copy"
+// true. So /tweak renders the page before it applies the batch and again after,
+// on a desktop (1440) and a phone (390), in light and in dark, and attaches the
+// eight pictures to the round's task under their slot names
+// (task-visuals.TWEAK_RENDER_SLOTS: before-desktop-light … after-phone-dark).
+//
+// HOW IT RENDERS. Exactly the way the page reader reads (scripts/gds/page-reader.js):
+// the hall through the hall-preview harness with the pinned fixture account, the
+// landing and status surfaces through the ui-design kit's stub, one browser from
+// the kit's launchBrowser (system Edge or Chrome; nothing is downloaded), the
+// clock pinned, the page's first state from its .states.json. A page that pins
+// one colour mode is shot in that mode for both of its "light" and "dark" slots,
+// and the run says so, rather than inventing a mode the page does not have.
+// Full-page JPEG, so a long page still fits under the store's 4 MB cap.
+//
+// Run:  node scripts/gds/tweak-renders.js shoot --page <id> --phase before|after --out <dir>
+//       node scripts/gds/tweak-renders.js attach <task-id> --dir <dir>   (every slot file in <dir>)
+//       node scripts/gds/tweak-renders.js plan --page <id>              (what would be shot; no browser)
+//
+// Exit: 0 done · 1 a render or an upload failed · 2 usage · 3 no browser.
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const taskVisuals = require('../../modules/lifecycle/task-visuals');
+const { arg, cliClient, cliExit } = require('./cli-lib');
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+const EXT = 'jpg';
+const JPEG_QUALITY = 82;
+
+// ---- pure ------------------------------------------------------------------
+
+function slotName(phase, device, mode) {
+  return `${phase}-${device}-${mode}`;
+}
+
+// The shots for one phase of one page: one per device x mode, each carrying the
+// slot it fills and the mode the page will actually render in. `plan` is the
+// page's first render plan from page-reader.planRenders.
+function shotsFor(phase, plan) {
+  if (!taskVisuals.TWEAK_RENDER_PHASES.includes(phase)) throw new Error(`phase must be one of ${taskVisuals.TWEAK_RENDER_PHASES.join(', ')}`);
+  const pinned = plan && plan.pinnedMode ? plan.pinnedMode : null;
+  const out = [];
+  for (const [device, width] of Object.entries(taskVisuals.TWEAK_RENDER_DEVICES)) {
+    for (const mode of taskVisuals.TWEAK_RENDER_MODES) {
+      out.push({ slot: slotName(phase, device, mode), device, width, mode, renderMode: pinned || mode, file: `${slotName(phase, device, mode)}.${EXT}` });
+    }
+  }
+  return out;
+}
+
+// The page's first render plan, and whether its states file pins a mode. Reads
+// the inventory and the states file; no browser.
+function planForPage(pageId, { inventory, planRenders, root = REPO_ROOT }) {
+  const page = (inventory.pages || []).find((p) => p.id === pageId);
+  if (!page) return { ok: false, code: 'unknown_page', detail: { page: pageId } };
+  const plans = planRenders(page, { root });
+  const plan = plans[0];
+  let modes = null;
+  if (page.states_files && page.states_files.length) {
+    try { modes = JSON.parse(fs.readFileSync(path.join(root, page.states_files[0]), 'utf8')).modes || null; } catch { modes = null; }
+  }
+  const pinnedMode = Array.isArray(modes) && modes.length === 1 ? modes[0] : null;
+  return { ok: true, page, plan: { ...plan, pinnedMode } };
+}
+
+// Which slot files a directory holds, in slot order, and which are missing.
+function slotFilesIn(dir, { exists = (p) => fs.existsSync(p) } = {}) {
+  const found = [];
+  const missing = [];
+  for (const slot of taskVisuals.TWEAK_RENDER_SLOTS) {
+    const hit = ['jpg', 'png', 'webp'].map((e) => path.join(dir, `${slot}.${e}`)).find(exists);
+    if (hit) found.push({ slot, file: hit });
+    else missing.push(slot);
+  }
+  return { found, missing };
+}
+
+// ---- the browser half --------------------------------------------------------
+
+async function shoot({ pageId, phase, out }) {
+  const reader = require('./page-reader.js');
+  const kit = require('../../modules/ui-design/kit/lib');
+  const inventory = JSON.parse(fs.readFileSync(path.join(REPO_ROOT, reader.INVENTORY_REL), 'utf8'));
+  const planned = planForPage(pageId, { inventory, planRenders: reader.planRenders });
+  if (!planned.ok) { console.error(`tweak-renders: ${planned.code} (${pageId})`); return 2; }
+  const { page, plan } = planned;
+  const shots = shotsFor(phase, plan);
+  if (plan.pinnedMode) console.log(`tweak-renders: ${pageId} pins the ${plan.pinnedMode} mode, so both of its mode slots are shot in ${plan.pinnedMode}.`);
+  fs.mkdirSync(out, { recursive: true });
+
+  let browser;
+  try { browser = await kit.launchBrowser(); } catch (e) {
+    console.error(`tweak-renders: ${e.message}`);
+    return e instanceof kit.NoBrowserError ? 3 : 1;
+  }
+  const stoppers = [];
+  let failed = 0;
+  try {
+    let base;
+    if (page.surface === 'builders') {
+      const h = await reader.startHarness(kit);
+      stoppers.push(h.stop);
+      base = h.base;
+    } else {
+      const s = await kit.startStub({ surface: reader.SURFACE_MODULE[page.surface] || page.surface, auth: plan.auth, prefix: plan.stub.prefix, child: plan.stub.child, fixtures: plan.stub.fixtures });
+      stoppers.push(s.stop);
+      base = s.base;
+    }
+    for (const shot of shots) {
+      const [W, H] = kit.SIZES[shot.width];
+      const ctx = await browser.newContext({ viewport: { width: W, height: H }, deviceScaleFactor: 1, colorScheme: shot.renderMode });
+      try {
+        if (ctx.clock && typeof ctx.clock.setFixedTime === 'function') await ctx.clock.setFixedTime(new Date(reader.PINNED_CLOCK));
+        const p = await ctx.newPage();
+        p.setDefaultTimeout(6000);
+        p.on('dialog', (d) => { d.dismiss().catch(() => {}); });
+        await p.goto(base + kit.withMode(plan.url, shot.renderMode, plan.modeQuery), { waitUntil: 'load', timeout: 45000 });
+        await p.evaluate(() => document.fonts.ready).catch(() => {});
+        await p.waitForTimeout(kit.SETTLE_MS);
+        try { await kit.runActions(p, plan.actions); } catch (e) { console.log(`  ${shot.slot}: an action failed (${String(e.message).split('\n')[0].slice(0, 100)}); shot as it stood`); }
+        await p.screenshot({ path: path.join(out, shot.file), fullPage: true, type: 'jpeg', quality: JPEG_QUALITY });
+        const kb = Math.round(fs.statSync(path.join(out, shot.file)).size / 1024);
+        console.log(`  ${shot.slot}: ${W}px ${shot.renderMode} -> ${shot.file} (${kb} KB)`);
+      } catch (e) {
+        failed += 1;
+        console.error(`  ${shot.slot}: NOT rendered (${String(e.message).split('\n')[0].slice(0, 160)})`);
+      } finally {
+        await ctx.close().catch(() => {});
+      }
+    }
+  } finally {
+    await browser.close().catch(() => {});
+    for (const stop of stoppers) stop();
+  }
+  console.log(`tweak-renders: ${shots.length - failed} of ${shots.length} ${phase} render(s) of ${pageId} in ${out}`);
+  return failed ? 1 : 0;
+}
+
+// ---- the upload half ---------------------------------------------------------
+
+async function attach({ taskId, dir }, deps = {}) {
+  const { found, missing } = slotFilesIn(dir, deps);
+  if (!found.length) { console.error(`tweak-renders: no slot files in ${dir} (expected ${taskVisuals.TWEAK_RENDER_SLOTS[0]}.${EXT} and the rest).`); return 1; }
+  const client = deps.client || await cliClient();
+  let failed = 0;
+  for (const { slot, file } of found) {
+    const img = taskVisuals.readImageFile(file);
+    if (!img.ok) { failed += 1; console.error(`  ${slot}: ${img.message}`); continue; }
+    const r = await client.tasks.postTasksIdVisualsSlot({ id: taskId, slot, body: { image_b64: img.buf.toString('base64'), content_type: img.contentType, alt: `${slot.replace(/-/g, ' ')} render of the page` } });
+    if (r.ok) console.log(`  ${slot}: attached (${Math.round(img.buf.length / 1024)} KB)`);
+    else { failed += 1; console.error(`  ${slot}: upload failed (${r.status})`); }
+  }
+  if (missing.length) console.error(`tweak-renders: MISSING ${missing.length} slot(s): ${missing.join(', ')}. The Approval queue shows what is attached; shoot the missing phase and attach again.`);
+  console.log(`tweak-renders: ${found.length - failed} of ${taskVisuals.TWEAK_RENDER_SLOTS.length} render(s) attached to task ${taskId}.`);
+  return failed || missing.length ? 1 : 0;
+}
+
+async function main(args) {
+  const cmd = args[0];
+  if (cmd === 'shoot' || cmd === 'plan') {
+    const pageId = arg('--page', args);
+    if (!pageId) { console.error('usage: node scripts/gds/tweak-renders.js shoot --page <id> --phase before|after --out <dir>'); return 2; }
+    if (cmd === 'plan') {
+      const reader = require('./page-reader.js');
+      const inventory = JSON.parse(fs.readFileSync(path.join(REPO_ROOT, reader.INVENTORY_REL), 'utf8'));
+      const planned = planForPage(pageId, { inventory, planRenders: reader.planRenders });
+      if (!planned.ok) { console.error(`tweak-renders: ${planned.code} (${pageId})`); return 2; }
+      for (const phase of taskVisuals.TWEAK_RENDER_PHASES) for (const s of shotsFor(phase, planned.plan)) console.log(`${s.slot}\t${s.width}px\t${s.renderMode}\t${planned.plan.url}`);
+      return 0;
+    }
+    const phase = arg('--phase', args);
+    const out = arg('--out', args);
+    if (!taskVisuals.TWEAK_RENDER_PHASES.includes(phase) || !out) { console.error('usage: node scripts/gds/tweak-renders.js shoot --page <id> --phase before|after --out <dir>'); return 2; }
+    return shoot({ pageId, phase, out: path.resolve(out) });
+  }
+  if (cmd === 'attach') {
+    const taskId = Number(args[1]);
+    const dir = arg('--dir', args);
+    if (!Number.isInteger(taskId) || taskId <= 0 || !dir) { console.error('usage: node scripts/gds/tweak-renders.js attach <task-id> --dir <dir>'); return 2; }
+    return attach({ taskId, dir: path.resolve(dir) });
+  }
+  console.error('usage: node scripts/gds/tweak-renders.js shoot|attach|plan … (see the file header)');
+  return 2;
+}
+
+if (require.main === module) {
+  main(process.argv.slice(2)).then((code) => cliExit(code), (e) => { console.error(`tweak-renders: ${e.stack || e.message}`); cliExit(1); });
+}
+
+module.exports = { shotsFor, planForPage, attach };

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.1062'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.1064'; // 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_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/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