@bongos/core 1.19.1062 → 1.19.1064

package/docs/page-inventory.json

@@ -10,10 +10,10 @@
     "An id changes only when the host prefix, the data-page value or the file name changes; that is a rename, and records keyed on the old id move with it."
   ],
   "counts": {
-    "pages": 37,
+    "pages": 38,
     "surfaces": 3,
-    "with_states": 30,
-    "states": 149
+    "with_states": 31,
+    "states": 155
   },
   "surfaces": [
     {
@@ -22,7 +22,7 @@
       "at": "modules/hall-ui/public",
       "answers_at": "host prefix builders.",
       "origin": "https://builders.{apex}",
-      "pages": 30
+      "pages": 31
     },
     {
       "id": "landing",
@@ -932,6 +932,38 @@
         "out"
       ]
     },
+    {
+      "id": "builders:tweak-editor",
+      "surface": "builders",
+      "module": "hall-ui",
+      "page": "tweak-editor",
+      "id_from": "data-page",
+      "title": "Tweak a page",
+      "document_title": "Tweak a page — {{worldName}}",
+      "path": "/tweak-editor",
+      "url": "https://builders.{apex}/tweak-editor",
+      "files": [
+        "modules/hall-ui/public/tweak-editor.html",
+        "modules/hall-ui/public/style.css",
+        "modules/hall-ui/public/tweak-editor.css",
+        "modules/hall-ui/public/shell.js",
+        "modules/hall-ui/public/palette.js",
+        "modules/hall-ui/public/dom-utils.js",
+        "modules/hall-ui/public/tweak-editor-lib.js",
+        "modules/hall-ui/public/tweak-editor.js"
+      ],
+      "states_files": [
+        "modules/hall-ui/public/tweak-editor.states.json"
+      ],
+      "states": [
+        "doc",
+        "typed",
+        "chrome",
+        "submitted",
+        "picking",
+        "out"
+      ]
+    },
     {
       "id": "builders:watch",
       "surface": "builders",

package/docs/page-readings.json

@@ -5,7 +5,7 @@
   "adr": "0341 D3",
   "reread": "node scripts/gds/page-reader.js --stale",
   "how": ["Generated by node scripts/gds/page-reader.js (BV2.TW04, task 1004315; ADR 0341 D3). Do not hand-edit.","One entry per page of docs/page-inventory.json. Lines are in page order: the default state first, and a line only another state shows sits where that state shows it, with its state named.","placement: placed = a docs/copy-registry.json row renders it (file, line, string_id); shared = shell text every page of the surface carries (top bar, sidebar, footer), with its row when the registry has one; unplaced = the registry cannot place it (a rewrite becomes an engineer task, ADR 0341 D4).","text keeps {…} where the registry row has a hole, or where a value the page read from its API was filled in. A string that is only such data is counted under omitted.data, not listed.","reading_hash is over the non-shared lines (key, section, text); files_hash is over the page's inventory files. --check compares files_hash only and never opens a browser.","Rendered through the hall-preview harness (hall) and the ui-design kit stub (landing, status), at 1280x800 with the clock pinned, so a reading is the fixture world's page."],
-  "counts": {"pages":37,"lines":3616,"placed":1117,"shared":243,"unplaced":2256,"omitted_data":1969},
+  "counts": {"pages":38,"lines":3636,"placed":1131,"shared":247,"unplaced":2258,"omitted_data":2010},
   "pages": [
     {
       "id": "builders:atlas",
@@ -2908,6 +2908,39 @@
         {"key":"L0082","section":"This is your sky.","text":"{…} file{…}","placement":"placed","file":"modules/hall-ui/public/gate.js","line":151,"string_id":"3efa67dc6e07"}
       ]
     },
+    {
+      "id": "builders:tweak-editor",
+      "surface": "builders",
+      "title": "Tweak a page",
+      "states_read": ["doc","typed","chrome","submitted","picking","out"],
+      "files_hash": "8f56ba72c49a8e62",
+      "reading_hash": "4c09a72e05c598fd",
+      "counts": {"lines":20,"placed":14,"shared":4,"unplaced":2},
+      "omitted": {"data":41},
+      "notes": [],
+      "lines": [
+        {"key":"L0001","section":"skip link","text":"Skip to content","placement":"shared","file":"modules/hall-ui/public/shell.js","line":776,"string_id":"87cee78ca134"},
+        {"key":"L0002","section":"top bar","text":"Tweak a page","placement":"shared","file":"modules/hall-ui/public/tweak-editor.html","line":32,"string_id":"72a29648399b","state":"chrome"},
+        {"key":"L0003","section":"top bar","text":"Jump to…","placement":"shared","file":"modules/hall-ui/public/shell.js","line":496,"string_id":"eba610d25523","state":"chrome"},
+        {"key":"L0004","section":"top bar","text":"Ctrl K","placement":"shared","state":"chrome"},
+        {"key":"L0005","section":"page top","text":"← studio","placement":"placed","file":"modules/hall-ui/public/tweak-editor.html","line":52,"string_id":"3ad4e941d265"},
+        {"key":"L0006","section":"page top","text":"{…} of {…}","placement":"placed","file":"modules/hall-ui/public/sky-panel.js","line":120,"string_id":"73c1372b43d9","state":"typed","occurrences":2},
+        {"key":"L0007","section":"page top","text":"open the page ↗","placement":"placed","file":"modules/hall-ui/public/tweak-editor.html","line":56,"string_id":"08f1f614253c"},
+        {"key":"L0008","section":"page top","text":"download .docx","placement":"placed","file":"modules/hall-ui/public/tweak-editor.html","line":57,"string_id":"fcec9cad1c69"},
+        {"key":"L0009","section":"page top","text":"upload .docx","placement":"placed","file":"modules/hall-ui/public/tweak-editor.html","line":58,"string_id":"432def6844b7"},
+        {"key":"L0010","section":"page top","text":"submit page","placement":"placed","file":"modules/hall-ui/public/tweak-editor.html","line":60,"string_id":"9ec19e32f86f"},
+        {"key":"L0011","section":"{…}","text":"Every word on the page, in the order it shows them. Type over anything, or download it, work in Word, and upload it back.","placement":"placed","file":"modules/hall-ui/public/tweak-editor.html","line":67,"string_id":"9904ca3d33e8"},
+        {"key":"L0012","section":"{…}","text":"was: {…}","placement":"unplaced","occurrences":2},
+        {"key":"L0013","section":"{…} project{…}","text":"{…} project{…}","placement":"placed","file":"modules/hall-ui/public/fleet.js","line":39,"string_id":"771bef3d31b5","occurrences":2},
+        {"key":"L0014","section":"{…} project{…}","text":"was: {…}","placement":"unplaced"},
+        {"key":"L0015","section":"{…} is in.","text":"{…} is in.","placement":"placed","file":"modules/hall-ui/public/tweak-editor.js","line":361,"string_id":"55b949873848","state":"submitted"},
+        {"key":"L0016","section":"{…} is in.","text":"It comes back to your studio once it is applied, and nothing ships until you have seen it.","placement":"placed","file":"modules/hall-ui/public/tweak-editor.html","line":80,"string_id":"bef8dbf78170","state":"submitted"},
+        {"key":"L0017","section":"{…} is in.","text":"next up","placement":"placed","file":"modules/hall-ui/public/tweak-editor.html","line":83,"string_id":"73bfe3b1ff54","state":"submitted"},
+        {"key":"L0018","section":"{…} is in.","text":"take next","placement":"placed","file":"modules/hall-ui/public/tweak-editor.html","line":89,"string_id":"d4f99c118825","state":"submitted"},
+        {"key":"L0019","section":"{…} is in.","text":"pick another","placement":"placed","file":"modules/hall-ui/public/tweak-editor.html","line":90,"string_id":"b6ceacaad5e5","state":"submitted"},
+        {"key":"L0020","section":"{…} is in.","text":"back to the studio","placement":"placed","file":"modules/hall-ui/public/tweak-editor.html","line":91,"string_id":"24a2c1d958da","state":"submitted"}
+      ]
+    },
     {
       "id": "builders:watch",
       "surface": "builders",

package/modules/copy-desk/page-status.js

@@ -511,7 +511,70 @@ function composeNext({ inventory, readings, tasks, asks, builderId, alternatives
   };
 }
 
+// The margin note a line carries in the editor (ADR 0341 D4, TW10): shared
+// shell text changes on every page, and a line the applier cannot place goes
+// to an engineer at submit (pages.goesToEngineer, the submit's own rule).
+const EDITOR_NOTES = Object.freeze({ shared: 'changes this on every page', engineer: 'goes to an engineer' });
+
+function editorNote(line) {
+  if (pages.goesToEngineer(line)) return 'engineer';
+  return line.placement === 'shared' ? 'shared' : null;
+}
+
+// GET /copy-desk/pages/:pageId/draft — what the editor (task 1004321 / BV2.TW10)
+// opens on: every line of the page reading in page order, the open round and
+// whether the caller holds it, and the saved draft. A draft saved on another
+// reading is not applied to these lines (its keys may name other lines); it is
+// reported as `draft_on_older_reading` instead.
+//
+// `readingPage` is the page's entry in docs/page-readings.json (null when the
+// page has not been read); `round` is the page's open round as the lifecycle
+// port lists it, or null.
+function composeEditor({ page, readingPage, round, builderId }) {
+  const lines = ((readingPage && readingPage.lines) || []).map((l) => ({
+    key: l.key, section: l.section, text: l.text, placement: l.placement, note: editorNote(l),
+  }));
+  const readingHash = readingPage ? readingPage.reading_hash || null : null;
+  let draft = null;
+  let olderReading = false;
+  if (round) {
+    const d = pages.parseDraftBlock(round.description);
+    if (d.ok) {
+      if (d.draft.reading_hash === readingHash) {
+        const keys = new Set(lines.map((l) => l.key));
+        draft = {
+          reading_hash: d.draft.reading_hash,
+          saved_at: d.draft.saved_at || null,
+          lines: d.draft.lines.filter((l) => keys.has(l.key)).map((l) => ({ key: l.key, after: l.after })),
+        };
+      } else {
+        olderReading = true;
+      }
+    }
+  }
+  const heldByYou = !!round && round.holder_id != null && String(round.holder_id) === String(builderId);
+  return {
+    ok: true,
+    page_id: page.id,
+    page: { id: page.id, title: page.title || page.id, surface: page.surface, surface_word: surfaceWord(page.surface), path: page.path || null, url: page.url || null },
+    reading: { reading_hash: readingHash, read: !!readingPage, lines },
+    notes: EDITOR_NOTES,
+    round: round ? {
+      task_id: String(round.id),
+      state: roundState(round),
+      status: round.status,
+      held_by_you: heldByYou,
+      holder: round.holder_id != null ? { id: String(round.holder_id), login: round.holder_login || null } : null,
+      claim: { method: 'POST', path: `/copy-desk/pages/${page.id}/claim` },
+    } : null,
+    draft,
+    draft_on_older_reading: olderReading,
+    counter: { changed: draft ? draft.lines.length : 0, total: lines.length },
+  };
+}
+
 module.exports = {
+  composeEditor,
   TALLY_REASON_PREFIX,
   NEXT_ALTERNATIVES,
   NEXT_TIERS,

package/modules/copy-desk/pages.js

@@ -448,6 +448,7 @@ module.exports = {
   sameDraft,
   saveDraftInto,
   freezeBatch,
+  goesToEngineer,
   unplacedSourceRef,
   unplacedTaskTitle,
   unplacedTaskBody,

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

@@ -17,6 +17,7 @@
 // TW08 (task 1004319) added the draft autosave and the submit, and TW09 (task
 // 1004320) the Word round trip, GET and POST /copy-desk/pages/:pageId/draft.docx:
 // the upload lands in the round's DRAFT, through the autosave's own port call.
+// TW10 (task 1004321) added the editor's read, GET /copy-desk/pages/:pageId/draft.
 //
 // THE RANK SHAPE, AND WHY IT IS ASYMMETRIC:
 //
@@ -972,6 +973,35 @@ module.exports = function buildCopyDeskRouter() {
     }
   });
 
+  // -------------------------------------------------------------------------
+  // GET /copy-desk/pages/:pageId/draft — what the tweak editor opens on (task
+  // 1004321 / BV2.TW10, ADR 0341 D4): every line of the page reading in page
+  // order with its margin note, the open round and whether the caller holds
+  // it, and the saved draft (only on the current reading). The read the PUT
+  // below saves over, and the .docx download's own data as JSON.
+  //
+  // rank: any signed-in builder, as the download: the words are the page's
+  //       own and the draft sits on a task every builder can read.
+  // -------------------------------------------------------------------------
+  router.get('/copy-desk/pages/:pageId/draft', api.requireBuilder, async (req, res) => {
+    try {
+      const found = pageOrFail(req, res);
+      if (!found) return;
+      const { page, pageId } = found;
+      const lifecycle = pageReadsOrFail(res);
+      if (!lifecycle) return;
+      const readingPage = readingPageOrFail(res, pageId);
+      if (!readingPage) return;
+      const round = openRoundOf(await lifecycle.listPageTweakTasks({ pageId }), pageId);
+      const out = pageStatus.composeEditor({ page, readingPage, round, builderId: req.builder.id });
+      res.set('Cache-Control', 'no-store');
+      res.json(out);
+    } catch (err) {
+      log.error({ err }, 'GET /copy-desk/pages/:pageId/draft failed');
+      if (!res.headersSent) res.fail('copy_page_editor_failed', 500);
+    }
+  });
+
   // -------------------------------------------------------------------------
   // PUT /copy-desk/pages/:pageId/draft — autosave the artist's draft (task
   // 1004319 / BV2.TW08, ADR 0341 D4).

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

@@ -0,0 +1,137 @@
+// tweak-editor-lib.js — the tweak editor's pure half (task 1004321 / BV2.TW10,
+// ADR 0341 D4; docs/design/mocks/tweak-mode/Editor.dc.html).
+//
+// The editor is one paper document holding every word of a page, in the order
+// the page shows them, typed over in place and autosaved. Everything here is a
+// pure function of the editor read (GET /copy-desk/pages/:pageId/draft) and the
+// words in the boxes, so a test imports this file and runs the real rules:
+//
+//   sectionsOf(lines)      consecutive runs of one section, as the page shows
+//                          them (a section that recurs gets its heading again —
+//                          the Word download's own rule, docx.js)
+//   noteFor(line, value)   the margin note: shared and engineer lines carry
+//                          theirs, a changed line carries "was: <old words>"
+//   draftBody(...)         the WHOLE draft the autosave PUTs: every changed,
+//                          non-empty line as { key, after }
+//   counterText(...)       "2 of 75 rewritten · saved"
+//   liveUrl(url, loc)      the page's live address, {apex} resolved from the
+//                          hall's own host (shell.js APEX_ORIGIN's rule)
+//
+// Node-require-safe (the roadmap-timeline.js pattern): assignment is the only
+// eval-time side effect, and only when a window exists.
+(() => {
+  'use strict';
+
+  // The ADR's words (D4), and the read's own `notes` wins when it carries them.
+  const NOTES = Object.freeze({ shared: 'changes this on every page', engineer: 'goes to an engineer' });
+
+  function sectionsOf(lines) {
+    const out = [];
+    for (const l of lines || []) {
+      const last = out[out.length - 1];
+      if (last && last.name === l.section) last.lines.push(l);
+      else out.push({ name: l.section, lines: [l] });
+    }
+    return out;
+  }
+
+  // What the box holds is compared as typed, so a trailing space the artist is
+  // still typing counts as a change; the server tidies before it stores.
+  function isChanged(line, value) {
+    return typeof value === 'string' && value !== line.text;
+  }
+
+  // The mock's rule: a shared or engineer line always shows its own note, and
+  // any other changed line shows the words it replaced.
+  function noteFor(line, value, notes) {
+    const n = notes || NOTES;
+    if (line.note === 'shared') return { kind: 'shared', text: n.shared || NOTES.shared };
+    if (line.note === 'engineer') return { kind: 'engineer', text: n.engineer || NOTES.engineer };
+    if (isChanged(line, value)) return { kind: 'was', text: `was: ${line.text}` };
+    return null;
+  }
+
+  // An empty box is not a rewrite: removing words from a page is a code change
+  // (the server's line_empty), so an emptied line is left out of the save and
+  // the page keeps its words until the artist types new ones.
+  function isEmpty(value) {
+    return !String(value == null ? '' : value).trim();
+  }
+
+  function draftBody(readingHash, lines, values) {
+    const out = [];
+    for (const l of lines || []) {
+      const v = values[l.key];
+      if (isChanged(l, v) && !isEmpty(v)) out.push({ key: l.key, after: v });
+    }
+    return { reading_hash: readingHash, lines: out };
+  }
+
+  function changedCount(lines, values) {
+    return draftBody('', lines, values).lines.length;
+  }
+
+  const SAVE_WORDS = Object.freeze({ saved: 'saved', saving: 'saving…', failed: 'not saved', idle: 'saved' });
+  function counterText(changed, total, save) {
+    return `${changed} of ${total} rewritten · ${SAVE_WORDS[save] || SAVE_WORDS.saved}`;
+  }
+
+  // The editor's starting words: the page's own, with the saved draft laid over.
+  function initialValues(lines, draft) {
+    const values = {};
+    for (const l of lines || []) values[l.key] = l.text;
+    for (const d of (draft && draft.lines) || []) if (d && Object.prototype.hasOwnProperty.call(values, d.key)) values[d.key] = d.after;
+    return values;
+  }
+
+  // The mock shows two rows once a line passes 64 characters; the page grows
+  // each box to its words instead, so this is only the first paint's guess.
+  function rowsFor(value) {
+    return String(value || '').length > 64 ? 2 : 1;
+  }
+
+  // {apex} is the instance's own domain. The hall answers at builders.<apex>
+  // (or status.<apex>), so the apex is this host without that prefix — the
+  // shell's own APEX_ORIGIN rule. On a plain-http dev host the scheme follows.
+  function liveUrl(url, loc) {
+    if (!url) return null;
+    const host = String(loc.host || '').replace(/^(builders|status)\./, '');
+    let out = String(url).replace('{apex}', host);
+    if (loc.protocol === 'http:') out = out.replace(/^https:\/\//, 'http://');
+    return out;
+  }
+
+  // "uploaded · 3 lines from your doc" (the mock's words).
+  function uploadedLabel(merge) {
+    const n = merge && Array.isArray(merge.from_file) ? merge.from_file.length : 0;
+    return `uploaded · ${n} ${n === 1 ? 'line' : 'lines'} from your doc`;
+  }
+
+  // A page's name as the artist reads it ("Home", "Projects"). The inventory's
+  // title is the page's <title>, and on the apex that is a branding template
+  // ("{{productName}}: {{tagline}}"), which is not a name. So a templated title
+  // names its page by what follows the product ("{{productName}} — projects"
+  // is "Projects"), and a surface's front page, path "/", is "Home".
+  function displayTitle(page) {
+    const t = String((page && page.title) || (page && page.page_id) || '');
+    if (!/\{\{/.test(t)) return t;
+    if (page.path === '/') return 'Home';
+    const rest = t.replace(/^\{\{[^}]*\}\}\s*(?:—|-|:)\s*/, '').replace(/\{\{[^}]*\}\}/g, '').trim();
+    if (!rest) return 'Home';
+    return rest.charAt(0).toUpperCase() + rest.slice(1);
+  }
+
+  // The page id rides the query string: ?page=landing:index.
+  const PAGE_ID_RE = /^[a-z0-9-]+:[a-z0-9-]+$/;
+  function pageIdFrom(search) {
+    const m = /[?&]page=([^&#]*)/.exec(String(search || ''));
+    if (!m) return null;
+    let id = '';
+    try { id = decodeURIComponent(m[1]); } catch (_) { return null; }
+    return PAGE_ID_RE.test(id) ? id : null;
+  }
+
+  const api = { NOTES, sectionsOf, isChanged, noteFor, draftBody, changedCount, counterText, initialValues, rowsFor, liveUrl, uploadedLabel, displayTitle, pageIdFrom };
+  if (typeof window !== 'undefined') window.OTBTweakEditor = api;
+  if (typeof module !== 'undefined' && module.exports) module.exports = api;
+})();