@bongos/core 1.21.43 → 1.21.45

package/tests/hall_street.mjs

@@ -32,6 +32,7 @@ const PUB = path.join(ROOT, 'modules/hall-ui/public');
 const require = createRequire(import.meta.url);
 const City = require(path.join(PUB, 'city-draw.js'));
 const S = require(path.join(PUB, 'street-draw.js'));
+require(path.join(PUB, 'street-desk.js')); // hangs GovDesk (the line rule's fit) on the global the street reads
 const read = (f) => fs.readFileSync(path.join(PUB, f), 'utf8');
 const NOW = Date.parse('2026-10-02T12:00:00.000Z'); // a Friday
 
@@ -185,17 +186,118 @@ test('every civic door is the prototype\'s door, and every door opens where its
 
 // ── what the street says comes from the docket, and only from it ───────────
 
-test('a pin per open matter at its building, in its state, up to three stacked, needs first as the docket ordered them', () => {
-  const ms = ['needs', 'needs', 'moving', 'settled'].map((state, i) => matter({ id: `blockers:${i}`, state }));
+// task 1004569 (owner, 2026-10-04): the pins stacked on top of each other and
+// their text overlapped. Deliberate change from the prototype's drawing: ONE
+// pin per building, in the tier of its most important matter.
+test('one pin per building, never more: it carries the count of the building\'s open matters and every matter, most important first', () => {
+  const ms = [
+    matter({ id: 'blockers:0', state: 'moving' }), matter({ id: 'blockers:1', state: 'needs' }),
+    matter({ id: 'blockers:2', state: 'settled' }), matter({ id: 'blockers:3', state: 'needs', deadline: '2026-10-03T06:00:00.000Z' }),
+    matter({ id: 'board:9', building: 'charter', state: 'moving' }),
+  ];
   const m = model({ docket: docket(ms) });
   const here = m.pins.filter((p) => p.building === 'planning');
-  assert.equal(here.length, S.MAX_PINS_PER_BUILDING);
-  assert.deepEqual(here.map((p) => p.state), ['needs', 'needs', 'moving']);
-  assert.equal(new Set(here.map((p) => p.y)).size, 3, 'stacked, one label above the other');
-  assert.ok(here.every((p) => p.x === here[0].x));
+  assert.equal(here.length, 1, 'one pin, not one per matter');
+  assert.equal(m.pins.length, 2, 'one per building that has a matter');
+  assert.equal(here[0].count, '3', 'three open (the settled one is not open)');
+  assert.deepEqual(here[0].matters, ['blockers:3', 'blockers:1', 'blockers:0', 'blockers:2'], 'urgent, needs, moving, settled: the pager\'s order');
+  assert.equal(here[0].key, 'blockers:3', 'the pin opens on its most important matter');
+  assert.equal(here[0].state, 'urgent');
+  assert.match(here[0].aria, /^3 open at planning, the first needs you within a day/);
   assert.equal(m.cols.find((c) => c.key === 'planning').state, '0 goals open', 'Planning says how many goals are open');
 });
 
+test('a building\'s pin takes the tier of its most important matter: urgent is needs-you due within 24 hours', () => {
+  const tierOf = (list) => model({ docket: docket(list) }).pins.find((p) => p.building === 'planning').state;
+  const at = (h) => new Date(NOW + h * 3600000).toISOString();
+  assert.equal(tierOf([matter({ id: 'a:1', state: 'needs', deadline: at(23) })]), 'urgent', 'due inside a day');
+  assert.equal(tierOf([matter({ id: 'a:1', state: 'needs', deadline: at(-5) })]), 'urgent', 'overdue');
+  assert.equal(tierOf([matter({ id: 'a:1', state: 'needs', deadline: at(25) })]), 'needs', 'due after a day');
+  assert.equal(tierOf([matter({ id: 'a:1', state: 'moving', deadline: at(1) })]), 'moving', 'a deadline never makes moving work urgent');
+  assert.equal(tierOf([matter({ id: 'a:1', state: 'moving' }), matter({ id: 'a:2', state: 'needs' })]), 'needs', 'needs beats moving, wherever it stands in the docket');
+  assert.equal(tierOf([matter({ id: 'a:1', state: 'settled' }), matter({ id: 'a:2', state: 'moving' })]), 'moving');
+  assert.equal(tierOf([matter({ id: 'a:1', state: 'settled' })]), 'settled');
+  assert.equal(tierOf([matter({ id: 'a:1', state: 'weird' })]), 'moving', 'an unknown state is never needs');
+});
+
+test('labels: urgent and needs-you show one short label cut by the line rule; moving waits for a hover; settled is a dot with no label and no count', () => {
+  const Desk = require(path.join(PUB, 'street-desk.js'));
+  const ms = [
+    matter({ id: 'board:1', building: 'charter', state: 'needs', short: 'a very long matter name that runs on', deadline: '2026-10-06T12:00:00.000Z' }),
+    matter({ id: 'blockers:2', building: 'automation', state: 'moving', short: 'moving work' }),
+    matter({ id: 'removal_proposals:3', building: 'treasury', state: 'settled', short: 'settled thing' }),
+  ];
+  const m = model({ docket: docket(ms), goals: [1, 2, 3, 4].map((i) => goal(i)) });
+  const by = Object.fromEntries(m.pins.map((p) => [p.building, p]));
+  assert.equal(by.charter.label, Desk.fit('a very long matter name that runs on', S.PIN_LABEL - 6) + ' · tue', 'fit() cuts the name, the deadline survives');
+  assert.ok(by.charter.label.length <= S.PIN_LABEL);
+  assert.equal(by.charter.shown, true);
+  assert.deepEqual([by.automation.label, by.automation.shown], ['moving work', false], 'moving: the label is there for hover and focus, not shown');
+  assert.deepEqual([by.treasury.label, by.treasury.count, by.treasury.shown], ['', '', false], 'settled: no label, no count');
+});
+
+// A dense docket: every civic building holds several matters in every tier,
+// with long names and deadlines, and work waits at Review.
+function denseDocket() {
+  const keys = ['charter', 'rules', 'disputes', 'people', 'planning', 'automation', 'release', 'treasury'];
+  const ms = [];
+  keys.forEach((b, i) => {
+    const day = (h) => new Date(NOW + h * 3600000).toISOString();
+    ms.push(matter({ id: `dense:${b}:1`, building: b, state: i % 3 === 2 ? 'moving' : 'needs', short: `${b} needs a long careful decision`, deadline: i % 2 ? day(6) : day(30 + i * 24) }));
+    ms.push(matter({ id: `dense:${b}:2`, building: b, state: 'needs', short: `second ${b} matter` }));
+    ms.push(matter({ id: `dense:${b}:3`, building: b, state: 'moving', short: `moving at ${b}` }));
+    ms.push(matter({ id: `dense:${b}:4`, building: b, state: 'settled', short: `settled at ${b}` }));
+  });
+  [1, 2, 3, 4].forEach((i) => ms.push(matter({ id: `criteria_uat:${i}`, source: 'criteria_uat', building: 'review', state: 'needs', title: `Criterion ${i}` })));
+  return docket(ms);
+}
+const meets = (a, b) => a.x0 < b.x1 && b.x0 < a.x1 && a.y0 < b.y1 && b.y0 < a.y1;
+function overlaps(boxes) {
+  const hits = [];
+  boxes.forEach((a, i) => boxes.slice(i + 1).forEach((b) => { if (meets(a, b)) hits.push([a.key, b.key]); }));
+  return hits;
+}
+
+test('no overlap, ever: on a dense docket the collision pass lifts or quiets labels until no two shown labels meet, both modes', () => {
+  for (const mode of ['dark', 'light']) {
+    const m = model({ mode, docket: denseDocket(), goals: [1, 2, 3, 4].map((i) => goal(i)) });
+    const shown = S.shownLabels(m.pins);
+    assert.deepEqual(overlaps(shown), [], `${mode}: no two shown labels meet`);
+    assert.ok(shown.length >= 7, 'the labels that need you show');
+    assert.equal(new Set(m.pins.map((p) => p.building)).size, m.pins.length, 'one pin per building');
+    // The street's roofs stagger the pins' heights, so its own row rarely
+    // collides. The worst case is every pin at one height (a future roof, a
+    // new building): the pass must still keep every shown label clear, lifting
+    // some and quieting the lowest tier, never a higher one over a lower one.
+    const flat = m.pins.map((p) => ({ ...p, y: 300, h: 78, shown: false, lifted: false }));
+    const naive = flat.filter((p) => ['urgent', 'needs', 'queue'].includes(p.rank)).map((p) => ({ key: p.key, ...S.labelBox(p) }));
+    assert.ok(overlaps(naive).length > 0, 'at one height, without the pass, labels would meet');
+    S.placeLabels(flat);
+    assert.deepEqual(overlaps(S.shownLabels(flat)), [], `${mode}: worst case, still no two shown labels meet`);
+    assert.ok(flat.some((p) => p.lifted), 'a label stepped up to the alternate height');
+    const T = ['urgent', 'needs', 'queue'];
+    flat.filter((p) => T.includes(p.rank) && !p.shown).forEach((q) => {
+      const at = (y) => S.labelBox({ x: q.x, y, label: q.label });
+      const blockers = flat.filter((p) => p.shown && (meets(S.labelBox(p), at(300)) || meets(S.labelBox(p), at(300 - S.PIN_STACK))));
+      assert.ok(blockers.length && blockers.every((b) => T.indexOf(b.rank) <= T.indexOf(q.rank)), `${q.key} gave way only to an equal or higher tier`);
+    });
+  }
+});
+
+test('the collision pass places in tier order: when only one of two can show, the lower tier waits for hover and keeps its count and colour', () => {
+  const pins = [
+    { key: 'lo', rank: 'needs', state: 'needs', x: 100, y: 400, h: 78, label: 'aaaaaaaaaaaaaaaa', count: '2' },
+    { key: 'hi', rank: 'urgent', state: 'urgent', x: 120, y: 400, h: 78, label: 'bbbbbbbbbbbbbbbb', count: '1' },
+    { key: 'mid', rank: 'needs', state: 'needs', x: 110, y: 400, h: 78, label: 'cccccccccccccccc', count: '3' },
+  ];
+  S.placeLabels(pins);
+  const by = Object.fromEntries(pins.map((p) => [p.key, p]));
+  assert.deepEqual([by.hi.shown, by.hi.lifted], [true, false], 'the urgent label keeps the pin\'s own height');
+  assert.deepEqual([by.lo.shown, by.lo.lifted, by.lo.y, by.lo.h], [true, true, 400 - S.PIN_STACK, 78 + S.PIN_STACK], 'the next steps up to the alternate height');
+  assert.equal(by.mid.shown, false, 'the third has nowhere to go: its label waits for hover');
+  assert.deepEqual([by.mid.state, by.mid.count], ['needs', '3'], 'its count and colour stay');
+});
+
 test('no docket: no pins, the readings say so, and nothing is invented', () => {
   const m = S.streetModel({ docket: null, goals: [goal(1)], rollups: [], mode: 'dark', now: NOW });
   assert.equal(m.pins.length, 0);
@@ -443,8 +545,9 @@ function fakeDom() {
   return { document, byId, html, focused };
 }
 
-async function bootPage({ feeds = {}, stored = null, osDark = true, hash = '', shell = undefined } = {}) {
+async function bootPage({ feeds = {}, stored = null, osDark = true, hash = '', shell = undefined, width = 1440 } = {}) {
   const { document, byId, html, focused } = fakeDom();
+  byId.get('streetWindow').clientWidth = width;
   const store = new Map(stored ? [['hall-theme', stored]] : []);
   const calls = [];
   const listeners = {};
@@ -468,6 +571,8 @@ async function bootPage({ feeds = {}, stored = null, osDark = true, hash = '', s
   vm.runInContext(read('city-draw.js'), ctx);
   vm.runInContext(read('street-draw.js'), ctx);
   vm.runInContext(read('street-card.js'), ctx);
+  vm.runInContext(read('street-inside.js'), ctx);
+  vm.runInContext(read('street-desk.js'), ctx);
   vm.runInContext(read('street.js'), ctx);
   await window.GovStreetPage.ready;
   const key = (t, e) => (listeners[t] || []).forEach((fn) => fn(e));
@@ -482,16 +587,23 @@ const FEEDS = (ms, goals = [goal(1)], rollups = [rollup(1, { done: 2, active: 1
 });
 
 test('the page reads the four feeds and draws the docket\'s pins, the readings and the header', async () => {
-  const ms = [matter({ id: 'board:1', building: 'charter', state: 'needs' }), matter({ id: 'blockers:2', state: 'moving' })];
+  const soon = new Date(Date.now() + 3 * 3600000).toISOString();
+  const ms = [matter({ id: 'board:1', building: 'charter', state: 'needs', deadline: soon }), matter({ id: 'blockers:2', state: 'moving' }), matter({ id: 'blockers:3', state: 'moving' }), matter({ id: 'access_requests:4', building: 'people', state: 'needs' }), matter({ id: 'override_requests:5', building: 'release', state: 'settled' })];
   const p = await bootPage({ feeds: FEEDS(ms) });
   assert.deepEqual([...p.calls].sort(), ['/api/bongos/builders/95/earnings', '/api/bongos/goals', '/api/bongos/goals/rollups', '/api/bongos/government/docket']);
   const pins = p.byId.get('streetPins').children;
-  assert.deepEqual(pins.map((s) => s.className).sort(), ['street-pin street-pin--moving', 'street-pin street-pin--needs']);
-  assert.equal(pins.find((s) => s.attrs['data-matter'] === 'board:1').children[1].children[0].className, 'street-pin__ring', 'a needs pin pulses');
+  assert.deepEqual(pins.map((s) => s.className).sort(), ['street-pin street-pin--moving', 'street-pin street-pin--needs street-pin--shown', 'street-pin street-pin--settled', 'street-pin street-pin--urgent street-pin--shown']);
+  const pin = (k) => pins.find((s) => s.attrs['data-matter'] === k);
+  assert.equal(pin('board:1').children[1].children[0].className, 'street-pin__ring', 'only the urgent pin pulses');
+  assert.ok(!pin('access_requests:4').children[1].children.some((c) => c.className === 'street-pin__ring'), 'a needs-you pin is solid orange, no ring');
+  assert.equal(pin('blockers:2').attrs['data-matters'], 'blockers:2 blockers:3');
+  assert.deepEqual(pin('blockers:2').children[1].children.map((c) => c.className), ['', 'street-pin__badge'], 'the glyph, then the count of open matters');
+  assert.equal(pin('blockers:2').children[1].children[1].textContent, '2');
+  assert.equal(pin('override_requests:5').children[1].children.length, 0, 'a settled pin is a plain dot');
   assert.equal(p.byId.get('streetSigns').children.length, 6);
   assert.ok(p.byId.get('streetSigns').children.every((a) => /^\/builders\/street#building=/.test(a.attrs.href)));
-  assert.equal(p.byId.get('hudNeeds').textContent, '1');
-  assert.equal(p.byId.get('hudMoving').textContent, '1');
+  assert.equal(p.byId.get('hudNeeds').textContent, '2');
+  assert.equal(p.byId.get('hudMoving').textContent, '2');
   assert.equal(p.byId.get('hudShare').textContent, '$24');
   assert.equal(p.byId.get('hudDot').className, 'street-hud__dot street-hud__dot--hot');
   assert.equal(p.byId.get('streetDoors').children.length, 10, 'nine buildings and one district, each a door');
@@ -515,6 +627,67 @@ test('a pin opens its short card, Escape closes it and focus goes back to the pi
   assert.equal(p.focused.el.attrs['data-matter'], 'board:1');
 });
 
+test('the card pager: a pin with several matters opens the most important with "1 of N", and previous/next reach every matter there', async () => {
+  const ms = [matter({ id: 'blockers:1', state: 'moving', title: 'Third' }), matter({ id: 'blockers:2', state: 'needs', title: 'First' }), matter({ id: 'blockers:3', state: 'needs', title: 'Second' }), matter({ id: 'blockers:4', state: 'settled', title: 'Fourth' })];
+  const p = await bootPage({ feeds: FEEDS(ms) });
+  const pin = p.byId.get('streetPins').children.find((s) => s.attrs['data-building'] === 'planning');
+  pin.fire('click');
+  const body = p.byId.get('streetCardBody');
+  const pager = () => body.children[0];
+  const btn = (dir) => pager().children.find((c) => c.attrs['data-act'] === 'page-' + dir);
+  assert.equal(p.byId.get('streetCardTitle').textContent, 'First', 'the most important matter first');
+  assert.equal(pager().className, 'mcard-pager');
+  assert.equal(pager().children[1].textContent, '1 of 4');
+  const seen = [p.byId.get('streetCardTitle').textContent];
+  for (let i = 0; i < 3; i++) { btn('next').fire('click'); seen.push(p.byId.get('streetCardTitle').textContent); }
+  assert.deepEqual(seen, ['First', 'Second', 'Third', 'Fourth'], 'next reaches every matter at the building');
+  assert.equal(pager().children[1].textContent, '4 of 4');
+  assert.equal(p.focused.el && p.focused.el.attrs['data-act'], 'page-next', 'focus stays on the arrow');
+  btn('next').fire('click');
+  assert.equal(p.byId.get('streetCardTitle').textContent, 'First', 'and wraps');
+  btn('prev').fire('click');
+  assert.equal(p.byId.get('streetCardTitle').textContent, 'Fourth', 'previous goes back, wrapping too');
+  assert.equal(p.byId.get('streetCard').hidden, false, 'all without leaving the street');
+  assert.equal(p.byId.get('streetPins').children.find((s) => s.attrs['data-building'] === 'planning').attrs['aria-expanded'], 'true', 'the pin still says its card is open');
+  p.key('keydown', { key: 'Escape', preventDefault() {} });
+  assert.equal(p.focused.el.attrs['data-building'], 'planning', 'Escape returns focus to the pin');
+  // one matter: no pager
+  const q = await bootPage({ feeds: FEEDS([matter({ id: 'board:1', building: 'charter' })]) });
+  q.byId.get('streetPins').children[0].fire('click');
+  assert.ok(!q.byId.get('streetCardBody').children.some((c) => c.className === 'mcard-pager'), 'one matter, no pager');
+});
+
+test('no two shown labels meet on a dense docket at 1440, 1024, 390 and 320 wide, as the page draws them', async () => {
+  for (const width of [1440, 1024, 390, 320]) {
+    const p = await bootPage({ feeds: { ...FEEDS([]), '/api/bongos/government/docket': denseDocket(), '/api/bongos/goals': { goals: [1, 2, 3, 4].map((i) => goal(i)) } }, width });
+    const s = Number(p.byId.get('streetBoard').style['--street-scale']);
+    assert.ok(s > 0, `${width}: the board is scaled`);
+    const pins = p.byId.get('streetPins').children;
+    assert.equal(pins.length, 9, `${width}: one pin per civic building`);
+    const shown = pins.filter((el) => /street-pin--shown/.test(el.className)).map((el) => {
+      const b = S.labelBox({ x: parseFloat(el.style.left), y: parseFloat(el.style.top), label: el.children[0].textContent });
+      return { key: el.attrs['data-matter'], x0: b.x0 * s, x1: b.x1 * s, y0: b.y0 * s, y1: b.y1 * s };
+    });
+    assert.ok(shown.length >= 5, `${width}: labels show`);
+    assert.deepEqual(overlaps(shown), [], `${width}: no two shown labels meet on screen`);
+  }
+});
+
+test('the header counts wear the pins\' colours, so they double as the legend', () => {
+  const html = read('street.html');
+  assert.match(html, /<span class="street-hud__dot" id="hudDot" aria-hidden="true"><\/span>\s*<span class="street-label">needs you<\/span>/);
+  assert.match(html, /<span class="street-hud__dot street-hud__dot--moving" aria-hidden="true"><\/span>\s*<span class="street-label">moving<\/span>/);
+  const css = read('street.css').replace(/\/\*[\s\S]*?\*\//g, '');
+  assert.match(css, /\.street-hud__dot \{[^}]*border: 1\.5px solid var\(--accent\)/, 'needs you is orange, a ring while nothing waits');
+  assert.match(css, /\.street-hud__dot--hot \{ background: var\(--accent\); \}/);
+  assert.match(css, /\.street-hud__dot--moving \{[^}]*background: var\(--ink\)/, 'moving is the moving pin\'s ink');
+  assert.match(css, /\.street-pin--moving \.street-pin__head \{[^}]*background: var\(--ink\)/);
+  assert.match(css, /\.street-pin--urgent \.street-pin__head, \.street-pin--needs \.street-pin__head \{ background: var\(--accent\)/);
+  // size carries the tier too, so it reads without colour
+  const size = (t) => Number((css.match(new RegExp(`\\.street-pin--${t} \\.street-pin__head \\{ width: (\\d+)px`)) || [])[1] || 28);
+  assert.ok(size('urgent') > size('needs') && size('needs') > size('moving') && size('moving') > size('settled'), 'urgent > needs > moving > settled');
+});
+
 test('the switch reads and writes the hall\'s own theme preference and redraws the street', async () => {
   const p = await bootPage({ feeds: FEEDS([]), stored: 'light', osDark: true });
   assert.equal(p.html.attrs['data-theme'], 'light', 'the stored hall choice beats the OS');

package/tests/hall_tweak_editor.mjs

@@ -635,7 +635,7 @@ try {
     assert.match(HTML, /<body data-page="tweak-editor"[^>]*data-fullscreen-switch/);
     assert.equal((HTML.match(/<h1\b/g) || []).length, 1);
     assert.ok(HTML.indexOf('tweak-editor-lib.js') < HTML.indexOf('tweak-editor.js?'), 'the lib loads first');
-    assert.match(HTML, /shell\.js\?v=2026-10-04-nolegacy/);
+    assert.match(HTML, /shell\.js\?v=2026-10-04-paintbrush/);
     assert.equal(/fonts\.googleapis\.com\/css/.test(HTML), false);
     for (const id of ['tw-bar', 'tw-counter', 'tw-open', 'tw-open-more', 'tw-divider', 'tw-openwrap', 'tw-open-menu', 'tw-open-tab', 'tw-open-split', 'tw-frame', 'tw-frame-view', 'tw-split-close', 'tw-download', 'tw-upload', 'tw-file', 'tw-submit', 'tw-paper', 'tw-doc', 'tw-notice', 'tw-done', 'tw-take', 'tw-pick', 'tw-picks', 'tw-refused', 'tw-refused-title', 'tw-refused-list', 'tw-refused-next', 'tw-refused-download', 'tw-refused-close']) {
       assert.ok(new RegExp(`id="${id}"`).test(HTML), `#${id} is in the markup`);

package/tests/page_notes_panel.mjs

@@ -76,8 +76,9 @@ const flush = () => new Promise((r) => setTimeout(r, 0));
 
 test('THE PALETTE: in the top bar in Artistry alone, right before the switch, and gone when the mode changes', () => {
   const p = boot({ session: { 'hall-craft': 'artistry' } });
-  assert.deepEqual(p.tools().map((t) => t.id), ['craft-tool-palette']);
-  assert.equal(p.tools()[0].nextSibling, p.sw, 'it sits right before the mode switch');
+  assert.deepEqual(p.tools().map((t) => t.id), ['craft-tool-palette', 'craft-tool-paintbrush'], 'the palette, then the paintbrush (task 1004497)');
+  assert.equal(p.tools()[0].nextSibling, p.tools()[1], 'the palette comes first');
+  assert.equal(p.tools()[1].nextSibling, p.sw, 'and the pair sits right before the mode switch');
   assert.equal(p.tools()[0].getAttribute('aria-label'), 'Write feedback on this page');
   for (const m of ['building', 'ideating', 'governing']) {
     p.craft.choose(m);
@@ -85,7 +86,7 @@ test('THE PALETTE: in the top bar in Artistry alone, right before the switch, an
   }
   p.craft.choose('artistry');
   p.craft.choose('artistry');
-  assert.equal(p.tools().length, 1, 'choosing Artistry twice draws one palette');
+  assert.equal(p.tools().length, 2, 'choosing Artistry twice draws one palette and one paintbrush');
   assert.equal(boot().tools().length, 0, 'and none with no mode at all');
 });
 

package/tests/paintbrush.mjs

@@ -0,0 +1,351 @@
+// tests/paintbrush.mjs — the Artistry paintbrush (task 1004497): a page's own
+// words, edited where they stand, as a proposed wording change.
+//
+// Runs the REAL paintbrush.js, with the REAL tweak-editor-lib.js and
+// studio-lib.js it shares with the editor and the studio, over a small page
+// (there is no jsdom here; the fake-DOM idiom of tests/page_notes_panel.mjs).
+// The task's done-when, as cases: an artist toggles editing, changes the words
+// a page shows, reviews the changes and sends them as one proposal; nobody
+// else's view changes — the page's words come back when editing ends, and the
+// only writes are the copy desk's own page-round routes (owner, 2026-10-04: the
+// edits are real wording changes, kept apart from the palette's feedback docs).
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import fs from 'node:fs';
+import path from 'node:path';
+import vm from 'node:vm';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const HALL = path.join(ROOT, 'modules/hall-ui/public');
+const read = (f) => fs.readFileSync(path.join(HALL, f), 'utf8');
+const BRUSH = read('paintbrush.js');
+const EDITOR_LIB = read('tweak-editor-lib.js');
+const STUDIO_LIB = read('studio-lib.js');
+const CRAFT = read('craft-mode.js');
+const CSS = read('style.css');
+
+// ---------- a small DOM: enough for the selectors paintbrush.js asks ----------
+function matchesOne(el, sel) {
+  sel = sel.trim();
+  const m = /^([a-z]+)?(?:#([\w-]+))?(?:\.([\w-]+))?(?:\[([\w-]+)(?:="([^"]*)")?\])?$/i.exec(sel);
+  if (!m) throw new Error('fake DOM cannot match ' + sel);
+  const [, tag, id, cls, attr, val] = m;
+  if (tag && el.tagName !== tag.toUpperCase()) return false;
+  if (id && el.id !== id) return false;
+  if (cls && !el.classList.contains(cls)) return false;
+  if (attr) {
+    if (attr === 'hidden') return !!el.hidden;
+    if (!el.hasAttribute(attr)) return false;
+    if (val !== undefined && el.getAttribute(attr) !== val) return false;
+  }
+  return true;
+}
+const matches = (el, sel) => sel.split(',').some((s) => matchesOne(el, s));
+
+class El {
+  constructor(tag, text) {
+    this.tagName = tag.toUpperCase();
+    this.attrs = {};
+    this.children = [];
+    this.parentNode = null;
+    this.id = '';
+    this.hidden = false;
+    this.dataset = {};
+    this.listeners = {};
+    this._text = text == null ? '' : String(text);
+    this._html = '';
+    const cls = new Set();
+    this.classList = {
+      add: (...c) => c.forEach((x) => cls.add(x)), remove: (...c) => c.forEach((x) => cls.delete(x)),
+      contains: (c) => cls.has(c), toggle: (c, on) => { if (on === undefined ? !cls.has(c) : on) cls.add(c); else cls.delete(c); },
+    };
+  }
+  add(child) { child.parentNode = this; this.children.push(child); return child; }
+  appendChild(c) { return this.add(c); }
+  removeChild(c) { this.children.splice(this.children.indexOf(c), 1); c.parentNode = null; return c; }
+  get childElementCount() { return this.children.length; }
+  get textContent() { return this.children.length ? this.children.map((c) => c.textContent).join('') : this._text; }
+  set textContent(v) { this.children = []; this._text = String(v); }
+  get innerHTML() { return this._html; }
+  set innerHTML(v) { this._html = String(v); }
+  set className(v) { String(v).split(/\s+/).filter(Boolean).forEach((c) => this.classList.add(c)); }
+  setAttribute(k, v) { this.attrs[k] = String(v); if (k === 'contenteditable') this.contentEditable = String(v); }
+  getAttribute(k) { return k in this.attrs ? this.attrs[k] : null; }
+  hasAttribute(k) { return k in this.attrs; }
+  removeAttribute(k) { delete this.attrs[k]; if (k === 'contenteditable') this.contentEditable = 'inherit'; }
+  closest(sel) { for (let n = this; n; n = n.parentNode) if (n.tagName && matches(n, sel)) return n; return null; }
+  querySelectorAll(sel) {
+    const out = [];
+    const walk = (n) => n.children.forEach((c) => { if (sel === '*' || matches(c, sel)) out.push(c); walk(c); });
+    walk(this);
+    return out;
+  }
+  querySelector(sel) { return this.querySelectorAll(sel)[0] || null; }
+  addEventListener(t, fn) { (this.listeners[t] ||= []).push(fn); }
+  focus() { this.ownerDocument.activeElement = this; }
+  blur() {}
+}
+
+// A page with words the reading lists, and words it must leave alone.
+function page() {
+  const body = new El('body');
+  body.dataset.page = 'roadmap';
+  body.dataset.pageTitle = 'Roadmap';
+  const main = body.add(new El('main'));
+  const h1 = main.add(new El('h1', 'Where the build is going'));
+  const lede = main.add(new El('p', 'Every version, from first idea to shipped.'));
+  const link = main.add(new El('a'));
+  link.setAttribute('href', '/goals');
+  const linkWords = link.add(new El('span', 'See every goal'));
+  const count = main.add(new El('p', '12 versions shipped'));            // a {…} hole line: the editor's
+  const btn = main.add(new El('button', 'Star this version'));          // a control: never editable
+  const stray = main.add(new El('p', 'Words the reading has never seen'));
+  const hiddenBox = main.add(new El('div'));
+  hiddenBox.hidden = true;
+  const hiddenWords = hiddenBox.add(new El('p', 'Nothing in flight right now.'));
+  const footer = body.add(new El('footer', 'Skip to content'));        // outside main
+  return { body, main, h1, lede, link, linkWords, count, btn, stray, hiddenWords, footer };
+}
+const READING = {
+  reading_hash: 'abc123',
+  read: true,
+  lines: [
+    { key: 'L0001', section: 'skip link', text: 'Skip to content', placement: 'shared' },
+    { key: 'L0002', section: 'page top', text: 'Where the build is going', placement: 'placed' },
+    { key: 'L0003', section: 'page top', text: 'Every version, from first idea to shipped.', placement: 'placed' },
+    { key: 'L0004', section: 'versions', text: 'See every goal', placement: 'placed' },
+    { key: 'L0005', section: 'versions', text: '{…} versions shipped', placement: 'placed' },
+    { key: 'L0006', section: 'versions', text: 'Star this version', placement: 'placed' },
+    { key: 'L0007', section: 'versions', text: 'Nothing in flight right now.', placement: 'unplaced' },
+  ],
+};
+
+function boot({ round = null, draft = null, claim = { status: 200, body: { ok: true } }, submit = { status: 200, body: { ok: true, outcome: 'submitted' } } } = {}) {
+  const p = page();
+  const head = new El('head');
+  const calls = [];
+  const docListeners = {};
+  const document = {
+    body: p.body, head, documentElement: new El('html'), activeElement: null,
+    currentScript: { src: 'https://h/builders/paintbrush.js?v=2026-10-04-test' },
+    querySelector: (sel) => p.body.querySelector(sel),
+    getElementById: (id) => p.body.querySelectorAll('*').find((n) => n.id === id) || null,
+    createElement: (t) => { const e = new El(t); e.ownerDocument = document; return e; },
+    addEventListener: (t, fn) => { (docListeners[t] ||= []).push(fn); },
+    removeEventListener: (t, fn) => { docListeners[t] = (docListeners[t] || []).filter((f) => f !== fn); },
+    execCommand() { return true; },
+    title: 'Roadmap — Builders hall',
+  };
+  for (const n of [p.body, ...p.body.querySelectorAll('*')]) n.ownerDocument = document;
+  let state = { round, draft };
+  const respond = (status, body) => Promise.resolve({ ok: status < 400, status, json: () => Promise.resolve(body) });
+  const fetch = (url, opts = {}) => {
+    const method = opts.method || 'GET';
+    calls.push({ method, url, body: opts.body ? JSON.parse(opts.body) : undefined, keepalive: !!opts.keepalive });
+    if (!url.startsWith('/api/bongos/copy-desk/pages/builders%3Aroadmap/')) return respond(404, {});
+    const rest = url.slice('/api/bongos/copy-desk/pages/builders%3Aroadmap/'.length);
+    if (method === 'GET' && rest === 'draft') return respond(200, { ok: true, page: { id: 'builders:roadmap', title: 'Roadmap' }, reading: READING, round: state.round, draft: state.draft });
+    if (method === 'POST' && rest === 'claim') {
+      if (claim.status < 400) state = { round: { task_id: '9', state: 'writing', held_by_you: true, holder: { login: 'me' } }, draft: null };
+      return respond(claim.status, claim.body);
+    }
+    if (method === 'PUT' && rest === 'draft') return respond(200, { ok: true, outcome: 'saved' });
+    if (method === 'POST' && rest === 'submit') return respond(submit.status, submit.body);
+    return respond(404, {});
+  };
+  const winListeners = {};
+  const window = { location: { pathname: '/roadmap' }, addEventListener: (t, fn) => { (winListeners[t] ||= []).push(fn); }, removeEventListener: (t, fn) => { winListeners[t] = (winListeners[t] || []).filter((f) => f !== fn); } };
+  const sandbox = { window, document, fetch, Promise, setTimeout, clearTimeout, JSON, Math, String, Array, Object };
+  window.window = window;
+  vm.createContext(sandbox);
+  // The two shared libs, as the page would have them once the tool loads them.
+  vm.runInContext(EDITOR_LIB, sandbox, { filename: 'tweak-editor-lib.js' });
+  vm.runInContext(STUDIO_LIB, sandbox, { filename: 'studio-lib.js' });
+  vm.runInContext(BRUSH, sandbox, { filename: 'paintbrush.js' });
+  const bar = () => p.body.querySelector('#paintbrush');
+  const fire = (type, ev) => (docListeners[type] || []).slice().forEach((fn) => fn(ev));
+  // Press a bar button by its data attribute.
+  const press = (attr) => {
+    const html = bar().innerHTML;
+    assert.match(html, new RegExp(attr), `the bar offers [${attr}]`);
+    const btn = new El('button');
+    btn.setAttribute(attr, '');
+    btn.parentNode = bar();
+    bar().listeners.click.forEach((fn) => fn({ target: btn }));
+  };
+  const type = (el, text) => { el.textContent = text; fire('input', { target: el }); };
+  const editable = () => p.body.querySelectorAll('*').filter((n) => n.hasAttribute('contenteditable'));
+  return { ...p, leave: () => (winListeners.pagehide || []).forEach((fn) => fn()), brush: window.OTBPaintbrush, calls, bar, press, type, fire, editable, html: document.documentElement, writes: () => calls.filter((c) => c.method !== 'GET') };
+}
+const settle = () => new Promise((r) => setTimeout(r, 5));
+
+test('craft-mode.js puts the paintbrush beside the palette in Artistry, loading its own script', () => {
+  assert.match(CRAFT, /\{ id: 'paintbrush', icon: 'brush', short: 'Edit words', label: 'Edit this page\\'s words', script: 'paintbrush.js', api: 'OTBPaintbrush' \}/);
+  const tools = /var TOOLS = \{([\s\S]*?)\n  \};/.exec(CRAFT)[1];
+  assert.match(tools, /^\s*artistry: \[/m, 'it is an Artistry tool');
+  assert.doesNotMatch(tools, /building:|ideating:|governing:/, 'and no other mode has one');
+});
+
+test('pressing it on a page nobody holds OFFERS the page — nothing is editable and nothing is written until the artist takes it', async () => {
+  const p = boot();
+  p.brush.open();
+  await settle();
+  assert.match(p.bar().innerHTML, /Take this page/);
+  assert.match(p.bar().innerHTML, /Nobody else sees them until then/);
+  assert.equal(p.editable().length, 0);
+  assert.deepEqual(p.writes(), [], 'reading the page writes nothing');
+  assert.equal(p.calls[0].url, '/api/bongos/copy-desk/pages/builders%3Aroadmap/draft', 'it reads this page by its reading id');
+});
+
+test('taking the page makes the words the reading lists editable where they stand — not shared chrome, holes, controls, hidden or unknown words', async () => {
+  const p = boot();
+  p.brush.open();
+  await settle();
+  p.press('data-pb-take');
+  await settle();
+  assert.deepEqual(p.writes().map((c) => c.method + ' ' + c.url.split('/').pop()), ['POST claim'], 'one claim, through the copy desk');
+  assert.deepEqual(p.editable().map((n) => n.textContent), ['Where the build is going', 'Every version, from first idea to shipped.', 'See every goal']);
+  for (const n of [p.count, p.btn, p.stray, p.hiddenWords, p.footer]) assert.ok(!n.hasAttribute('contenteditable'), `"${n.textContent}" stays as it is`);
+  assert.equal(p.h1.getAttribute('data-pb-key'), 'L0002');
+  assert.ok(p.html.classList.contains('pb-editing'));
+  assert.match(p.bar().innerHTML, /0 changes/);
+  assert.match(p.bar().innerHTML, /tweak editor/, 'the lines it cannot reach point to the editor');
+});
+
+test('a refused claim says why, in the artist\'s words, and leaves the page alone', async () => {
+  const p = boot({ claim: { status: 403, body: { ok: false, error: { code: 'not_an_artist', message: 'no' } } } });
+  p.brush.open();
+  await settle();
+  p.press('data-pb-take');
+  await settle();
+  assert.match(p.bar().innerHTML, /Only an artist can take a page/);
+  assert.equal(p.editable().length, 0);
+});
+
+test('a page another artist holds is not offered, and one already on its way is not either', async () => {
+  const held = boot({ round: { task_id: '9', state: 'writing', held_by_you: false, holder: { login: 'mira' } } });
+  held.brush.open();
+  await settle();
+  assert.match(held.bar().innerHTML, /mira is tweaking this page right now/);
+  assert.doesNotMatch(held.bar().innerHTML, /Take this page/);
+  const flight = boot({ round: { task_id: '9', state: 'submitted', held_by_you: false, holder: null } });
+  flight.brush.open();
+  await settle();
+  assert.match(flight.bar().innerHTML, /on its way to the site/);
+  assert.deepEqual([...held.writes(), ...flight.writes()], []);
+});
+
+test('typing saves the WHOLE draft to the page round, and a click on words inside a link does not follow it', async () => {
+  const p = boot({ round: { task_id: '9', state: 'writing', held_by_you: true, holder: { login: 'me' } } });
+  p.brush.open();
+  await settle();
+  assert.equal(p.editable().length, 3, 'a page you already hold opens straight into editing');
+  p.type(p.lede, 'Every version, from the first spark to shipped.');
+  p.fire('focusout', { target: p.lede });
+  await settle();
+  const put = p.writes().find((c) => c.method === 'PUT');
+  assert.ok(put, 'a save went out');
+  assert.match(put.url, /builders%3Aroadmap\/draft$/);
+  assert.deepEqual(JSON.parse(JSON.stringify(put.body)), { reading_hash: 'abc123', lines: [{ key: 'L0003', after: 'Every version, from the first spark to shipped.' }] });
+  assert.ok(p.lede.classList.contains('pb-word--changed'));
+  let prevented = false;
+  p.fire('click', { target: p.linkWords, preventDefault() { prevented = true; } });
+  assert.ok(prevented, 'the link around the words does not navigate while editing');
+});
+
+test('REVIEW lists every change as was/now, and SEND submits the page once and puts its own words back', async () => {
+  const p = boot({ round: { task_id: '9', state: 'writing', held_by_you: true, holder: { login: 'me' } } });
+  p.brush.open();
+  await settle();
+  p.type(p.h1, 'Where we are going');
+  p.type(p.linkWords, 'Every goal <b>here</b>');
+  p.press('data-pb-review');
+  await settle();
+  const html = p.bar().innerHTML;
+  assert.match(html, /Was<\/span> Where the build is going/);
+  assert.match(html, /Now<\/span> Where we are going/);
+  assert.match(html, /Every goal &lt;b&gt;here&lt;\/b&gt;/, 'what the artist typed is escaped in the review');
+  p.press('data-pb-send');
+  await settle();
+  const submits = p.writes().filter((c) => c.method === 'POST' && c.url.endsWith('/submit'));
+  assert.equal(submits.length, 1, 'one proposal for the page');
+  const lastPut = p.writes().filter((c) => c.method === 'PUT').pop();
+  assert.deepEqual(JSON.parse(JSON.stringify(lastPut.body.lines)), [{ key: 'L0002', after: 'Where we are going' }, { key: 'L0004', after: 'Every goal <b>here</b>' }], 'the saved draft held both changes before the submit');
+  assert.match(p.bar().innerHTML, /Sent for approval: 2 changes/);
+  assert.equal(p.h1.textContent, 'Where the build is going', 'the page shows its own words again');
+  assert.equal(p.linkWords.textContent, 'See every goal');
+  assert.equal(p.editable().length, 0);
+  assert.ok(!p.html.classList.contains('pb-editing'));
+});
+
+test('STOP EDITING keeps the draft saved and puts the page\'s words back', async () => {
+  const p = boot({ round: { task_id: '9', state: 'writing', held_by_you: true, holder: { login: 'me' } } });
+  p.brush.open();
+  await settle();
+  p.type(p.h1, 'A new heading');
+  p.press('data-pb-stop');
+  await settle();
+  assert.ok(p.writes().some((c) => c.method === 'PUT'), 'the change was saved first');
+  assert.ok(!p.writes().some((c) => c.url.endsWith('/submit')), 'stopping sends nothing');
+  assert.equal(p.h1.textContent, 'Where the build is going');
+  assert.equal(p.editable().length, 0);
+  assert.equal(p.bar(), null, 'the bar is gone');
+});
+
+test('a draft saved earlier comes back: the words show the artist\'s rewrite when editing resumes', async () => {
+  const p = boot({
+    round: { task_id: '9', state: 'writing', held_by_you: true, holder: { login: 'me' } },
+    draft: { reading_hash: 'abc123', lines: [{ key: 'L0002', after: 'Where it all goes' }] },
+  });
+  p.brush.open();
+  await settle();
+  assert.equal(p.h1.textContent, 'Where it all goes');
+  assert.ok(p.h1.classList.contains('pb-word--changed'));
+  assert.match(p.bar().innerHTML, /1 change/);
+});
+
+test('the only routes it writes are the copy desk\'s page round — never page-notes, never anything else', () => {
+  const routes = [...BRUSH.matchAll(/request\('(POST|PUT|PATCH|DELETE)', [^,]*?'\/([a-z-]+)'/g)].map((m) => m[1] + ' ' + m[2]);
+  assert.deepEqual(routes.sort(), ['POST claim', 'POST submit', 'PUT draft']);
+  assert.match(BRUSH, /var API = '\/api\/bongos\/copy-desk\/pages\/';/);
+  assert.doesNotMatch(BRUSH, /page-notes/);
+});
+
+test('its styles live in style.css, on the token tier', () => {
+  for (const sel of ['.pb {', '.pb__btn--go', '.pb-word {', '.pb-word--changed', '.pb__changes']) assert.ok(CSS.includes(sel), `style.css styles ${sel}`);
+  const block = CSS.slice(CSS.indexOf('/* THE PAINTBRUSH'), CSS.indexOf('/* THE BACK LINK'));
+  assert.doesNotMatch(block, /#[0-9a-f]{3,8}\b|rgba?\(/i, 'no colour literals: tokens only');
+});
+
+test('leaving the page mid-edit sends the last save with keepalive, so closing the tab does not lose it', async () => {
+  const p = boot({ round: { task_id: '9', state: 'writing', held_by_you: true, holder: { login: 'me' } } });
+  p.brush.open();
+  await settle();
+  p.type(p.h1, 'Typed, then the tab closed');
+  p.leave();
+  await settle();
+  const put = p.writes().find((c) => c.method === 'PUT');
+  assert.ok(put && put.keepalive, 'the save on the way out is a keepalive request');
+  assert.equal(put.body.lines[0].after, 'Typed, then the tab closed');
+});
+
+test('words only: bold, italic and underline keys do nothing in the words; elsewhere they are left alone', async () => {
+  const p = boot({ round: { task_id: '9', state: 'writing', held_by_you: true, holder: { login: 'me' } } });
+  p.brush.open();
+  await settle();
+  let prevented = 0;
+  for (const key of ['b', 'i', 'u']) p.fire('keydown', { key, ctrlKey: true, target: p.h1, preventDefault() { prevented++; } });
+  assert.equal(prevented, 3);
+  p.fire('keydown', { key: 'b', ctrlKey: true, target: p.stray, preventDefault() { prevented++; } });
+  assert.equal(prevented, 3, 'a key outside the edited words is not touched');
+});
+
+test('a word on the page matches its line however its spaces wrap, and one table serves every element', async () => {
+  const p = boot({ round: { task_id: '9', state: 'writing', held_by_you: true, holder: { login: 'me' } } });
+  p.lede.textContent = '  Every version,\n   from first idea to shipped. ';
+  p.brush.open();
+  await settle();
+  assert.equal(p.lede.getAttribute('data-pb-key'), 'L0003');
+  assert.doesNotMatch(BRUSH, /matchLine\(/, 'no per-element pattern matching: the hole-free lines are looked up by their words');
+});