@bongos/core 1.19.1062 → 1.19.1064

package/modules/hall-ui/public/tweak-editor.js

@@ -0,0 +1,447 @@
+// modules/hall-ui/public/tweak-editor.js — the tweak editor, /builders/tweak-editor
+// (task 1004321 / BV2.TW10, goal 1000095; ADR 0341 D4, D11 and D12).
+//
+// The artist's own flow: one paper document holding every word of a page, in
+// page order, typed over in place. It autosaves, round-trips through Word, and
+// submits once; then "<page> is in" names the next page (take next, pick
+// another, back to the studio). No terminal anywhere.
+//
+// Every write is copy-desk's, and the page issues only these (WRITES below):
+//   PUT  /copy-desk/pages/:pageId/draft        the autosave, the WHOLE draft
+//   POST /copy-desk/pages/:pageId/draft.docx   the Word file, merged into the draft
+//   POST /copy-desk/pages/:pageId/submit       freeze and queue the page
+//   POST <take.path>                           claim a page: "take this page",
+//                                              and "take next" on GET /copy-desk/next
+// Every target is the server's: the body names a line by its key and says what
+// it should say now, never where it lives. The pure rules are tweak-editor-lib.js.
+(() => {
+  'use strict';
+
+  const API = '/api/bongos';
+  const lib = window.OTBTweakEditor;
+  const api = window.BongosClient.createClient({ baseUrl: '', credentials: 'same-origin', throwOnError: false });
+  const { escapeHtml, toast, errMessage } = window.OTB;
+  const $ = (id) => document.getElementById(id);
+
+  const WRITES = Object.freeze({
+    draft: (id) => `${API}/copy-desk/pages/${id}/draft`,
+    upload: (id) => `${API}/copy-desk/pages/${id}/draft.docx`,
+    submit: (id) => `${API}/copy-desk/pages/${id}/submit`,
+    claim: (path) => `${API}${path}`,
+  });
+  const SAVE_DEBOUNCE_MS = 700;
+
+  // THE ARTBOARD IS FULL SCREEN. The first visit opens that way; after that the
+  // shell remembers the artist's own choice for this page.
+  try {
+    if (window.localStorage.getItem('hall-fullscreen:tweak-editor') === null && window.OTBShell) window.OTBShell.setFullscreen(true);
+  } catch (_) { /* private mode: the chrome shows, the honest default */ }
+
+  const st = {
+    pageId: null,
+    ed: null,          // the editor read
+    values: {},        // key -> the words in the box
+    writable: false,   // the caller holds the round
+    save: 'saved',     // saved | saving | failed
+    timer: null,
+    inflight: null,    // the save promise in flight
+    again: false,      // another save was asked for while one ran
+    lastSent: null,    // the JSON of the last body the server accepted
+    submitted: false,
+    next: null,        // GET /copy-desk/next
+    pick: null,        // the page "take next" takes
+  };
+
+  // ---------------------------------------------------------------------------
+  // paint
+  // ---------------------------------------------------------------------------
+
+  function lineById(key) { return st.ed.reading.lines.find((l) => l.key === key); }
+
+  function paintCounter() {
+    if (!st.ed) { $('tw-counter').textContent = ''; return; }
+    const changed = lib.changedCount(st.ed.reading.lines, st.values);
+    $('tw-counter').textContent = lib.counterText(changed, st.ed.reading.lines.length, st.save);
+  }
+
+  function noteHtml(line) {
+    const n = lib.noteFor(line, st.values[line.key], st.ed.notes);
+    return n ? { cls: `tw-note tw-note--${n.kind}`, text: n.text } : { cls: 'tw-note', text: '' };
+  }
+
+  function rowHtml(section, l) {
+    const v = st.values[l.key];
+    const n = noteHtml(l);
+    const id = `tw-${l.key}`;
+    return `<div class="tw-row" data-key="${escapeHtml(l.key)}">`
+      + `<label class="tw-sr" for="${id}">${escapeHtml(section)} line</label>`
+      + `<textarea id="${id}" class="tw-line${lib.isChanged(l, v) ? ' tw-line--changed' : ''}" rows="${lib.rowsFor(v)}" data-key="${escapeHtml(l.key)}"${st.writable ? '' : ' readonly'} spellcheck="true">${escapeHtml(v)}</textarea>`
+      + `<span class="${n.cls}" id="${id}-note">${escapeHtml(n.text)}</span>`
+      + '</div>';
+  }
+
+  function paintDoc() {
+    const doc = $('tw-doc');
+    const lines = st.ed.reading.lines;
+    if (!lines.length) {
+      doc.innerHTML = '<p class="tw-loading">This page shows no words the reader could find.</p>';
+      return;
+    }
+    doc.innerHTML = lib.sectionsOf(lines).map((s) => '<section class="tw-section">'
+      + `<h2>${escapeHtml(s.name)}</h2>`
+      + s.lines.map((l) => rowHtml(s.name, l)).join('')
+      + '</section>').join('');
+    doc.querySelectorAll('textarea.tw-line').forEach(fit);
+  }
+
+  // Each box grows to its words: the page scrolls, never a box.
+  function fit(ta) {
+    ta.style.height = 'auto';
+    ta.style.height = `${ta.scrollHeight}px`;
+  }
+
+  function paintRow(key) {
+    const l = lineById(key);
+    const ta = $(`tw-${key}`);
+    if (!l || !ta) return;
+    ta.classList.toggle('tw-line--changed', lib.isChanged(l, st.values[key]));
+    const n = noteHtml(l);
+    const note = $(`tw-${key}-note`);
+    note.className = n.cls;
+    note.textContent = n.text;
+  }
+
+  function paintHead() {
+    const p = st.ed.page;
+    $('tw-name').textContent = lib.displayTitle(p);
+    $('tw-surface').textContent = `· ${p.surface_word}`;
+    $('tw-title').textContent = lib.displayTitle(p);
+    document.title = `Tweak ${lib.displayTitle(p)} — ${document.title.split(' — ').pop()}`;
+    const live = lib.liveUrl(p.url, window.location);
+    const open = $('tw-open');
+    if (live) open.href = live; else open.hidden = true;
+    $('tw-download').disabled = false;
+    $('tw-upload').disabled = !st.writable;
+    $('tw-submit').disabled = !st.writable;
+  }
+
+  function notice(html) {
+    const n = $('tw-notice');
+    if (!html) { n.hidden = true; n.innerHTML = ''; return; }
+    n.innerHTML = html;
+    n.hidden = false;
+  }
+
+  // Why the words are read-only, and the one thing to do about it.
+  function roundNotice() {
+    const r = st.ed.round;
+    if (st.ed.draft_on_older_reading) {
+      notice('<p>The page changed after your draft was saved, so the draft is not shown over its new words. Rewrite the lines again here.</p>');
+    }
+    if (st.writable) return;
+    if (!r || r.state === 'draft' || (r.state === 'writing' && !r.holder)) {
+      notice('<p>Nobody is writing this page. Take it, and every line here is yours to type over.</p>'
+        + '<button class="tw-notice__act" id="tw-claim" type="button">take this page</button>');
+      return;
+    }
+    if (r.state === 'writing') {
+      notice(`<p>${escapeHtml(r.holder && r.holder.login ? r.holder.login : 'Another artist')} is writing this page now. You can read it, download it, or take another page from the studio.</p>`);
+      return;
+    }
+    notice('<p>This page has been submitted and is on its way to the site. Its words are frozen until it ships or is sent back.</p>');
+  }
+
+  function failPaper(msg) {
+    $('tw-doc').innerHTML = `<p class="tw-loading">${escapeHtml(msg)}</p>`;
+  }
+
+  // ---------------------------------------------------------------------------
+  // load
+  // ---------------------------------------------------------------------------
+
+  async function load() {
+    st.pageId = lib.pageIdFrom(window.location.search);
+    if (!st.pageId) {
+      const next = await api.request('GET', `${API}/copy-desk/next`);
+      const resume = next.ok && next.data && next.data.resume;
+      if (resume && resume.page_id) {
+        st.pageId = resume.page_id;
+        try { window.history.replaceState(null, '', `?page=${st.pageId}`); } catch (_) { /* old engine */ }
+      } else {
+        failPaper('No page is open. Take one from the studio, or take the next one below.');
+        showDone({ noPage: true });
+        return;
+      }
+    }
+    const res = await api.request('GET', `${API}/copy-desk/pages/${st.pageId}/draft`);
+    if (!res.ok) {
+      failPaper(errMessage(res.data) || 'The page could not be read. Reload to try again.');
+      return;
+    }
+    st.ed = res.data;
+    st.values = lib.initialValues(st.ed.reading.lines, st.ed.draft);
+    st.writable = !!(st.ed.round && st.ed.round.held_by_you && st.ed.round.state === 'writing');
+    st.lastSent = JSON.stringify(lib.draftBody(st.ed.reading.reading_hash, st.ed.reading.lines, st.values));
+    paintHead();
+    roundNotice();
+    paintDoc();
+    paintCounter();
+  }
+
+  // ---------------------------------------------------------------------------
+  // the autosave
+  // ---------------------------------------------------------------------------
+
+  function schedule() {
+    if (!st.writable) return;
+    window.clearTimeout(st.timer);
+    st.timer = window.setTimeout(() => { flush(); }, SAVE_DEBOUNCE_MS);
+  }
+
+  // Save now, if anything changed since the last accepted save. One save in
+  // flight at a time; a save asked for meanwhile runs once after it.
+  async function flush() {
+    window.clearTimeout(st.timer);
+    if (!st.writable || !st.ed) return true;
+    if (st.inflight) { st.again = true; await st.inflight; return st.save !== 'failed'; }
+    const body = lib.draftBody(st.ed.reading.reading_hash, st.ed.reading.lines, st.values);
+    const json = JSON.stringify(body);
+    if (json === st.lastSent) { st.save = 'saved'; paintCounter(); return true; }
+    st.save = 'saving';
+    paintCounter();
+    st.inflight = (async () => {
+      const r = await api.request('PUT', WRITES.draft(st.pageId), { body });
+      if (r.ok) {
+        st.lastSent = json;
+        st.save = 'saved';
+      } else {
+        st.save = 'failed';
+        refusal(r.data, 'Your words are still here, but the last change was not saved.');
+      }
+    })().catch(() => { st.save = 'failed'; });
+    await st.inflight;
+    st.inflight = null;
+    paintCounter();
+    if (st.again) { st.again = false; return flush(); }
+    return st.save !== 'failed';
+  }
+
+  // A refusal in the server's words (its what_this_means), with the lines it
+  // names: an upload's moved lines, a submit's refused ones. Every word is
+  // escaped, the file's first words included.
+  const words = (s) => String(s || '').replace(/_/g, ' ');
+  function refusalItems(d) {
+    if (Array.isArray(d.moved)) {
+      return d.moved.map((m) => `${m.section || 'a line'}${m.first_words ? `: “${m.first_words}”` : ''} (${words(m.change)})`);
+    }
+    if (Array.isArray(d.refused)) {
+      return d.refused.map((l) => `${l.section || l.key}: “${l.before || ''}” (${words(l.code)})`);
+    }
+    return [];
+  }
+  function refusal(data, fallback) {
+    const d = window.OTB.errDetails(data);
+    const msg = (d && d.what_this_means) || errMessage(data) || fallback;
+    const items = refusalItems(d || {});
+    notice(`<p>${escapeHtml(msg)}</p>${items.length ? `<ul>${items.map((i) => `<li>${escapeHtml(i)}</li>`).join('')}</ul>` : ''}`);
+  }
+
+  // Leaving with an unsaved change: one last save that outlives the page.
+  window.addEventListener('pagehide', () => {
+    if (!st.writable || !st.ed) return;
+    const body = lib.draftBody(st.ed.reading.reading_hash, st.ed.reading.lines, st.values);
+    if (JSON.stringify(body) === st.lastSent) return;
+    try {
+      fetch(WRITES.draft(st.pageId), { method: 'PUT', credentials: 'same-origin', keepalive: true, headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(body) });
+    } catch (_) { /* nothing more to try */ }
+  });
+
+  // ---------------------------------------------------------------------------
+  // the doors
+  // ---------------------------------------------------------------------------
+
+  async function download() {
+    await flush();
+    const a = document.createElement('a');
+    a.href = `${API}/copy-desk/pages/${st.pageId}/draft.docx`;
+    a.download = '';
+    document.body.appendChild(a);
+    a.click();
+    a.remove();
+    $('tw-download').textContent = 'downloaded .docx';
+  }
+
+  async function upload(file) {
+    if (!file || !st.writable) return;
+    await flush();
+    const btn = $('tw-upload');
+    btn.disabled = true;
+    btn.textContent = 'uploading…';
+    let r = null;
+    try {
+      const res = await fetch(WRITES.upload(st.pageId), {
+        method: 'POST',
+        credentials: 'same-origin',
+        headers: { 'Content-Type': file.type || 'application/octet-stream' },
+        body: file,
+      });
+      let data = null;
+      try { data = await res.json(); } catch (_) { data = null; }
+      r = { ok: res.ok, data };
+    } catch (_) {
+      r = { ok: false, data: null };
+    }
+    btn.disabled = false;
+    if (!r.ok) {
+      btn.textContent = 'upload .docx';
+      refusal(r.data, 'The file could not be read. Nothing was saved.');
+      return;
+    }
+    notice('');
+    for (const l of r.data.draft.lines) st.values[l.key] = l.after;
+    // A line the file set back to the page's words leaves the draft.
+    const inDraft = new Set(r.data.draft.lines.map((l) => l.key));
+    for (const l of st.ed.reading.lines) if (!inDraft.has(l.key) && lib.isChanged(l, st.values[l.key])) st.values[l.key] = l.text;
+    st.lastSent = JSON.stringify(lib.draftBody(st.ed.reading.reading_hash, st.ed.reading.lines, st.values));
+    st.save = 'saved';
+    paintDoc();
+    paintCounter();
+    btn.textContent = lib.uploadedLabel(r.data.merge);
+  }
+
+  async function submit() {
+    if (!st.writable || st.submitted) return;
+    const btn = $('tw-submit');
+    btn.disabled = true;
+    const saved = await flush();
+    if (!saved) { btn.disabled = false; return; }
+    const r = await api.request('POST', WRITES.submit(st.pageId), { body: {} });
+    if (!r.ok) {
+      btn.disabled = false;
+      refusal(r.data, 'The page could not be submitted.');
+      return;
+    }
+    st.submitted = true;
+    st.writable = false;
+    notice('');
+    document.querySelectorAll('textarea.tw-line').forEach((ta) => { ta.readOnly = true; });
+    $('tw-upload').disabled = true;
+    showDone({});
+  }
+
+  async function claim(path) {
+    const r = await api.request('POST', WRITES.claim(path), { body: {} });
+    if (!r.ok) {
+      refusal(r.data, 'The page could not be taken.');
+      return false;
+    }
+    return true;
+  }
+
+  // ---------------------------------------------------------------------------
+  // "<page> is in", and next up
+  // ---------------------------------------------------------------------------
+
+  function paintNext() {
+    const p = st.pick;
+    $('tw-next-title').textContent = p ? lib.displayTitle(p) : 'Nothing waits right now.';
+    $('tw-next-why').textContent = p ? p.why_line : 'Every page is taken or on its way. The studio shows when one comes free.';
+    $('tw-take').disabled = !p;
+    const others = st.next ? [st.next.recommended, ...(st.next.alternatives || [])].filter((c) => c && (!p || c.page_id !== p.page_id)) : [];
+    $('tw-pick').hidden = !others.length;
+    $('tw-picks').innerHTML = others.map((c) => `<button class="tw-pick" type="button" data-pick="${escapeHtml(c.page_id)}">${escapeHtml(lib.displayTitle(c))}</button>`).join('');
+  }
+
+  async function showDone({ noPage }) {
+    const title = $('tw-done-title');
+    if (noPage) {
+      title.textContent = 'No page is open.';
+      title.nextElementSibling.textContent = 'Take the next page, or pick one from the studio.';
+    } else {
+      title.textContent = `${lib.displayTitle(st.ed.page)} is in.`;
+    }
+    $('tw-bar').inert = true;
+    $('tw-paper').inert = true;
+    $('tw-done').hidden = false;
+    title.focus();
+    const r = await api.request('GET', `${API}/copy-desk/next`);
+    st.next = r.ok ? r.data : null;
+    st.pick = st.next ? st.next.recommended : null;
+    if (!r.ok) $('tw-next-why').textContent = 'The next page could not be read.';
+    paintNext();
+  }
+
+  async function takeNext() {
+    const p = st.pick;
+    if (!p) return;
+    const btn = $('tw-take');
+    btn.disabled = true;
+    const r = await api.request('POST', WRITES.claim(p.take.path), { body: {} });
+    if (!r.ok) {
+      btn.disabled = false;
+      const err = $('tw-done-error');
+      err.textContent = errMessage(r.data) || 'That page could not be taken. Pick another.';
+      err.hidden = false;
+      return;
+    }
+    window.location.assign(`${window.location.pathname}?page=${p.page_id}`);
+  }
+
+  // ---------------------------------------------------------------------------
+  // wire + boot
+  // ---------------------------------------------------------------------------
+
+  document.addEventListener('input', (ev) => {
+    const ta = ev.target;
+    if (!ta || !ta.classList || !ta.classList.contains('tw-line') || !st.writable) return;
+    st.values[ta.dataset.key] = ta.value;
+    fit(ta);
+    paintRow(ta.dataset.key);
+    paintCounter();
+    schedule();
+  });
+  document.addEventListener('focusout', (ev) => {
+    if (ev.target && ev.target.classList && ev.target.classList.contains('tw-line')) flush();
+  });
+  window.addEventListener('resize', () => { document.querySelectorAll('textarea.tw-line').forEach(fit); });
+
+  document.addEventListener('click', async (ev) => {
+    const t = ev.target;
+    if (t.closest('#tw-download')) { download(); return; }
+    if (t.closest('#tw-upload')) { $('tw-file').click(); return; }
+    if (t.closest('#tw-submit')) { submit(); return; }
+    if (t.closest('#tw-take')) { takeNext(); return; }
+    if (t.closest('#tw-claim')) {
+      const b = t.closest('#tw-claim');
+      b.disabled = true;
+      if (await claim(st.ed.round ? st.ed.round.claim.path : `/copy-desk/pages/${st.pageId}/claim`)) { notice(''); await load(); }
+      else b.disabled = false;
+      return;
+    }
+    if (t.closest('#tw-pick')) {
+      const open = $('tw-picks').hidden;
+      $('tw-picks').hidden = !open;
+      $('tw-pick').setAttribute('aria-expanded', open ? 'true' : 'false');
+      return;
+    }
+    const pick = t.closest('[data-pick]');
+    if (pick && st.next) {
+      st.pick = [st.next.recommended, ...(st.next.alternatives || [])].find((c) => c && c.page_id === pick.dataset.pick) || st.pick;
+      $('tw-picks').hidden = true;
+      $('tw-pick').setAttribute('aria-expanded', 'false');
+      $('tw-done-error').hidden = true;
+      paintNext();
+      $('tw-take').focus();
+    }
+  });
+  $('tw-file').addEventListener('change', (ev) => {
+    const f = ev.target.files && ev.target.files[0];
+    ev.target.value = '';
+    upload(f);
+  });
+
+  load().catch(() => {
+    failPaper('The page could not be read. Reload to try again.');
+    toast('The editor could not load.');
+  });
+})();

package/modules/hall-ui/public/tweak-editor.states.json

@@ -0,0 +1,99 @@
+{
+  "_": "The tweak editor (task 1004321 / BV2.TW10), built 1:1 on docs/design/mocks/tweak-mode/Editor.dc.html. Against the kit's own stub the page renders its could-not-read state (no /copy-desk feed), a state the floors must hold in. TO SEE IT POPULATED, point the kit at the hall-preview harness: `node scripts/hall-preview/server.js --port 4631 --fixture-me`, then `render.js --page '/builders/tweak-editor?page=landing:index' --base-in http://builders.localhost:4631 --base-out http://builders.localhost:4631`. The harness answers the read from fixtures/copy-desk__pages__draft.json (the real landing:index reading with the artboard's two rewrites as the saved draft), next up from copy-desk__next.json, and the autosave, the submit and the claim from its canned writes.",
+  "page": "/builders/tweak-editor?page=landing:index",
+  "surface": "hall-ui",
+  "stub": {
+    "prefix": "/builders/"
+  },
+  "modeQuery": false,
+  "ignoreRequests": [
+    "/api/(gds|bongos)/me$",
+    "/api/(gds|bongos)/me/",
+    "/api/(gds|bongos)/copy-desk/",
+    "/api/(gds|bongos)/core-update"
+  ],
+  "ignoreConsole": [
+    "/api/(gds|bongos)/",
+    "\\b401\\b",
+    "\\b403\\b",
+    "\\b404\\b",
+    "\\b501\\b",
+    "Unauthorized",
+    "Forbidden",
+    "Not Found",
+    "load failed"
+  ],
+  "states": {
+    "doc": {
+      "auth": true,
+      "_": "The artboard: full screen, the glass bar, the paper, two rewritten lines carrying the accent mark and was:, the shared and engineer margin notes.",
+      "actions": [
+        ["wait", 900]
+      ],
+      "expect": {
+        "visible": ["#tw-bar", "#tw-paper", "#tw-L0014", "#tw-submit"],
+        "hidden": ["#app-sidebar", "#tw-done"]
+      }
+    },
+    "typed": {
+      "auth": true,
+      "_": "A third line typed over: the counter moves and the autosave answers saved.",
+      "actions": [
+        ["wait", 900],
+        ["fill", "#tw-L0024", "See every project"],
+        ["wait", 1400]
+      ],
+      "expect": {
+        "visible": ["#tw-L0024"]
+      }
+    },
+    "chrome": {
+      "auth": true,
+      "_": "The shell's switch pressed: the editor in the hall chrome.",
+      "actions": [
+        ["wait", 900],
+        ["click", "#fullscreen-toggle"],
+        ["wait", 300]
+      ],
+      "expect": {
+        "visible": ["#app-sidebar", "#tw-bar", "#tw-paper"],
+        "attr": [["#fullscreen-toggle", "aria-pressed", "false"]]
+      }
+    },
+    "submitted": {
+      "auth": true,
+      "_": "Submit: Home is in, next up Projects, take next, pick another, back to the studio.",
+      "actions": [
+        ["wait", 900],
+        ["click", "#tw-submit"],
+        ["wait", 900]
+      ],
+      "expect": {
+        "visible": ["#tw-done", "#tw-take", "#tw-pick"]
+      }
+    },
+    "picking": {
+      "auth": true,
+      "_": "Pick another: the other pages open in place.",
+      "actions": [
+        ["wait", 900],
+        ["click", "#tw-submit"],
+        ["wait", 900],
+        ["click", "#tw-pick"],
+        ["wait", 300]
+      ],
+      "expect": {
+        "visible": ["#tw-picks"]
+      }
+    },
+    "out": {
+      "auth": false
+    }
+  },
+  "reducedMotion": {
+    "auth": true,
+    "actions": [
+      ["wait", 900]
+    ]
+  }
+}

package/modules/hall-ui/records/tweak-editor.md

@@ -0,0 +1,32 @@
+# The tweak editor — /tweak-editor, the whole page as one document (task 1004321)
+
+**BV2.TW10 (goal 1000095; [ADR 0341](../../../docs/adr/0341-the-page-is-the-unit-of-tweak-mode.md) D4, D11, D12).** The artist's own flow, built 1:1 on the owner-approved master design [`docs/design/mocks/tweak-mode/Editor.dc.html`](../../../docs/design/mocks/tweak-mode/README.md): over the night studio, a glass top bar (← studio, the page name and its surface, "N of M rewritten · saved", open the page ↗, download .docx, upload .docx, submit page) and one sheet of paper holding every line of the page in page order, typed over in place and autosaved. A changed line carries the accent mark and a faint "was:"; shared lines say "changes this on every page" and lines the applier cannot place say "goes to an engineer". Submit opens "<page> is in." with next up: take next, pick another, back to the studio.
+
+Files: `tweak-editor.html` (the markup), `tweak-editor.css` (the artboard's inline styles, one rule per element), `tweak-editor-lib.js` (the pure rules, `window.OTBTweakEditor`, node-require-safe) and `tweak-editor.js` (the reads, the autosave, the doors). What it settled:
+
+- **Which page.** `?page=<page id>` (`landing:index`). With none, the page the caller holds (`GET /copy-desk/next`'s `resume`), and with nothing held, the "is in" panel's next up, so a bare link still leads somewhere. The studio (TW16) links here.
+- **One read opens it.** `GET /copy-desk/pages/:pageId/draft` (added here: `GET /copy-desk/pages/:pageId` carries neither the lines nor the draft) answers every reading line with its margin note, the open round and `held_by_you`, and the saved draft, only on the current reading (`draft_on_older_reading` otherwise). The note is the server's: `engineer` is `pages.goesToEngineer`, the submit's own rule, so a shared line with no registry row says "goes to an engineer", which is what the submit will do with it.
+- **The autosave is the whole draft, debounced (700ms) and on blur**, one save in flight at a time, skipped when the body equals the last accepted one; a last `keepalive` PUT on `pagehide`. An emptied box is not saved (the server's `line_empty`: removing words is a code change), and the counter reads "not saved" with the server's own words above the paper when a save is refused.
+- **Holding decides writing.** A page nobody holds is read-only with one button, "take this page" (the claim); another builder's is read-only and names them; a submitted one is frozen. Upload and submit are the holder's only, as their routes are.
+- **Every write is named** (`WRITES`: the draft PUT, the .docx POST, the submit, the claim on a server-given `take.path`), and `tests/hall_tweak_editor.mjs` pins the list. The upload is a raw `fetch` because the generated client JSON-encodes every body.
+- **It opens full screen.** The artboard is the whole window, so the first visit sets the shell's switch (task 1004327) on; after that the shell remembers the artist's choice for this page. In full screen the switch button wears the room's glass, since the stage is dark in both themes.
+- **Names.** The inventory title is the page's `<title>`, which on the apex is a branding template (`{{productName}}: {{tagline}}`), so `displayTitle` names a templated page by what follows the product, and a surface's `/` is "Home" (the artboard's own word).
+
+## The palette is the artboard's, in both modes
+
+The paper is paper and the room is the room whatever the hall's theme: the stage (`main.tw-stage`) carries the artboard's values as `--tw-*`, never `:root` or `body`, so the hall chrome around it keeps its own light and dark (the sky precedent, `records/sky.md`). The sheet is therefore its own token tier and sits in `tests/hall_audit.mjs` `LITERAL_EXEMPT`.
+
+## Where it differs from the artboard, and what forced it
+
+- **The words are the reading's, not the sample's.** 75 lines for Home, not 33; the section names are the reading's (the page's own headings, from TW04's reader), not the artboard's hand-named "hero", "built on"; a section that recurs gets its heading again (consecutive runs, the .docx rule); the artboard's "page title" line is not on the page, so the reader does not list it.
+- **The shared note says "changes this on every page"**, not "on every landing page": ADR 0341 D4 and the task name those words. A shared line with no registry row says "goes to an engineer" (the submit files it as one).
+- **The paper grows and the window scrolls** (the hall's one-scroller seam), where the artboard's 860px sheet scrolled inside itself. So the bar is sticky, and its .07 glass lies on a backing of the room's black (`--tw-bar-back`), or the white paper passing under it turns the bar white and its words vanish. At rest over the room it reads as the artboard's bar.
+- **The "is in" scrim is .88, not .45.** The panel sits over the white paper, and at .45 its white and grey words measure about 2.9:1; at .88 every word clears 4.5:1 (the AA floor).
+- **A focused line gets a hairline accent ring** beside the artboard's warm wash (the hall's focus rule, `tests/hall_audit.mjs` §10).
+- **"pick another" opens the other pages in place** as chips under the actions (the studio artboard's own "pick another"), where the editor artboard linked to the studio, whose flow panel is TW16's.
+- **Boxes grow to their words** rather than the artboard's rows 1 or 2.
+- **Not on the artboard at all:** the phone layout (the bar becomes a two-row glass card, notes drop under their lines), the shell's full-screen button top right, the read-only and refusal notices on the paper, the chrome view (the switch off), and light mode.
+
+## The proof
+
+`tweak-editor.states.json` renders six states (doc, typed, chrome, submitted, picking, out). Against the kit's own stub the page renders its could-not-read state; populated, it renders against the hall-preview harness (`node scripts/hall-preview/server.js --port 4631 --fixture-me`), which answers the read from `copy-desk__pages__draft.json` (the real `landing:index` reading, through the real composer, with the artboard's two rewrites as the draft), next up from `copy-desk__next.json`, and the autosave, the submit and the claim from its CANNED WRITES (fixed answers that change nothing). All clean at 1440, 390 and 320, dark and light. The artboard needs the Design runtime, so for the review sheet it was rendered by expanding its own template over its own `renderVals()`; the ship notes of task 1004321 carry the sheet's path and every difference, which is the list above.

package/modules/lifecycle/db-grade.js

@@ -15,6 +15,7 @@ const { pool, withTx } = api;
 const seams = api;
 const { logGradeAttempt } = require('./db-analytics.js');
 const { mostRecentClaimHolderId } = require('./db-shared.js');
+const tweakHold = require('./page-tweak-hold.js');
 
 // applyGrade — V3.R18 (#209). Writes the subagent grader result to task_grades
 // and, if the grade passed, promotes completed→confirmed + awards credits.
@@ -132,7 +133,18 @@ async function applyGrade({ taskId, builderId, gradeResult, committedFiles = nul
     // state-machine SQL (FOR UPDATE, task_grades upsert, UPDATE tasks status,
     // claim-holder lookup, logGradeAttempt) stays here in the lifecycle.
     const reward = seams.resolveOptional('reward');
+
+    // THE HOLD (ADR 0341 D7; task 1004322 / BV2.TW11). A page tweak whose grade
+    // passes WAITS at completed for its artist: the grade row above is written,
+    // and the promotion below is withheld. TW12's approve performs it. Asked only
+    // on a pass at completed, and false for every task whose source is not
+    // exactly 'page-tweak', so every other grade takes the unchanged path below.
+    let held = false;
     if (gradeResult.passed && task.status === 'completed') {
+      const { rows: srcRows } = await client.query(`SELECT source FROM tasks WHERE id = $1`, [taskId]);
+      held = tweakHold.isPageTweak(srcRows[0] || null);
+    }
+    if (gradeResult.passed && task.status === 'completed' && !held) {
       await client.query(
         `UPDATE tasks
             SET status = 'confirmed',
@@ -195,6 +207,7 @@ async function applyGrade({ taskId, builderId, gradeResult, committedFiles = nul
     // !passed → task_grades row written above; task stays at completed; no
     // credits, no achievements. Builder can manual-confirm via /confirm if the
     // grade was wrong.
+    // held → the same row, the same completed; the pass is recorded and waits.
 
     return {
       taskId,
@@ -207,6 +220,9 @@ async function applyGrade({ taskId, builderId, gradeResult, committedFiles = nul
       ideaBonus, // V3.R27 (#247): { ideaBonusAwarded, bonusBuilderId, ideaId } | null
       netNegativeBonus,
       advanceToMerge: finalStatus === 'confirmed',
+      // task 1004322: true only for a page tweak whose pass is waiting for its
+      // artist. ship.js reads it to publish the branch without landing it.
+      held,
       justUnlocked,
       grade: {
         score: gradeResult.score,