@bongos/core 1.24.30 → 1.24.31

package/tests/home_gallery_widget.mjs

@@ -0,0 +1,220 @@
+// tests/home_gallery_widget.mjs — the artist's Home, the real gallery in a browser
+// (task 1005060, Home v16 step 3).
+//
+// Runs modules/hall-ui/public/home-gallery.js (and, for the craft switch, the city's
+// three files) in a real page with the reads stubbed by the hall-preview fixture: the
+// wall is asked for once, only in Artistry, Most popular first; the arrows and keys walk
+// it; the label opens closer on a click; the heart is the viewer's own, given and taken
+// back, and never changes size; Latest asks again in that order; full screen keeps the
+// signature and heart and drops the label; the full gallery hangs every work and a click
+// sits you in front of one; at phone width nothing scrolls sideways. Skips where no
+// system Edge or Chrome is installed.
+//
+// Run:  node --test tests/home_gallery_widget.mjs
+import assert from 'node:assert/strict';
+import { test, after } from 'node:test';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const lib = require(path.join(ROOT, 'modules', 'ui-design', 'kit', 'lib.js'));
+const pub = (f) => fs.readFileSync(path.join(ROOT, 'modules', 'hall-ui', 'public', f), 'utf8');
+const GALLERY = pub('home-gallery.js');
+const Lib = require(path.join(ROOT, 'modules', 'hall-ui', 'public', 'home-gallery.js'));
+const CSS = pub('home-city.css') + pub('home-gallery.css');
+const FIXTURE = fs.readFileSync(path.join(ROOT, 'scripts', 'hall-preview', 'fixtures', 'home__gallery.json'), 'utf8');
+const CITY = fs.readFileSync(path.join(ROOT, 'scripts', 'hall-preview', 'fixtures', 'home__city.json'), 'utf8');
+const N = JSON.parse(FIXTURE).works.length;
+
+let browser = null;
+try { browser = await lib.launchBrowser(); } catch (e) { if (!(e instanceof lib.NoBrowserError)) throw e; }
+after(() => browser && browser.close());
+const skip = !browser && 'no system Edge or Chrome';
+
+const stubs = `
+  window.__asked = [];
+  window.__GALLERY = ${FIXTURE};
+  window.__CITY = ${CITY};
+  window.BongosClient = { createClient: () => ({ request: async (m, p, o) => {
+    window.__asked.push(m + ' ' + p + (o && o.body ? ' ' + JSON.stringify(o.body) : ''));
+    if (p.startsWith('/api/bongos/home/gallery?')) {
+      const g = JSON.parse(JSON.stringify(window.__GALLERY));
+      if (p.endsWith('order=latest')) g.works.sort((a, b) => b.shipped.localeCompare(a.shipped));
+      return { ok: true, status: 200, data: g };
+    }
+    const h = /^\\/api\\/bongos\\/home\\/gallery\\/(\\d+)\\/heart$/.exec(p);
+    if (h && m === 'PUT') { const w = window.__GALLERY.works.find((x) => x.id === h[1]); return { ok: true, status: 200, data: { id: h[1], hearts: w.hearts + (o.body.on ? 1 : 0), mine: o.body.on } }; }
+    if (p.startsWith('/api/bongos/home/city')) return { ok: true, status: 200, data: window.__CITY };
+    return { ok: false, status: 404, data: null };
+  } }) };
+  window.OTBCraftMode = { iconHtml: () => '', choose: () => {} };
+  window.OTB = { contributeHallWidget(w) { window.__widget = w; } };`;
+
+async function boot({ width = 1440, height = 900, city = false, theme = 'dark' } = {}) {
+  const ctx = await browser.newContext({ viewport: { width, height }, reducedMotion: 'reduce' });
+  const page = await ctx.newPage();
+  await page.setContent(`<!doctype html><html data-theme="${theme}"><head><style>${CSS}</style></head><body><section id="home-city" class="scroll home-city" hidden></section></body></html>`);
+  await page.addScriptTag({ content: stubs });
+  await page.addScriptTag({ content: GALLERY });
+  if (city) {
+    for (const f of ['city-draw.js', 'home-city-draw.js', 'home-city.js']) await page.addScriptTag({ content: pub(f) });
+  } else {
+    await page.evaluate(() => { const h = document.getElementById('home-city'); h.classList.add('hc--gallery'); window.__g = window.OTBHomeGallery.attach(h); h.hidden = false; window.__g.show(true); });
+    await page.waitForFunction(() => document.querySelectorAll('.hg-hang').length > 0);
+  }
+  return { ctx, page };
+}
+
+const state = (page) => page.evaluate(() => ({
+  asked: window.__asked,
+  count: document.querySelector('.hg-count').textContent,
+  pressed: [...document.querySelectorAll('.hg-sort button')].map((b) => b.dataset.order + ':' + b.getAttribute('aria-pressed')),
+  first: document.querySelector('.hg-hang .hg-title i').textContent,
+}));
+
+test('the wall is asked for once, Most popular first, and hangs every work with its label, signature and heart', { skip }, async () => {
+  const { ctx, page } = await boot();
+  const s = await state(page);
+  const label = await page.evaluate(() => {
+    const h = document.querySelector('.hg-hang');
+    return { who: h.querySelector('.hg-who').textContent, bio: h.querySelector('.hg-bio').textContent, sig: h.querySelector('.hg-sig').textContent, heart: h.querySelector('.hg-heart').getAttribute('aria-pressed'), src: h.querySelector('img').getAttribute('src') };
+  });
+  await ctx.close();
+  assert.deepEqual(s.asked, ['GET /api/bongos/home/gallery?order=popular']);
+  assert.equal(s.count, `1 of ${N}`);
+  assert.deepEqual(s.pressed, ['popular:true', 'latest:false']);
+  assert.equal(label.who, 'Sana Okafor');
+  assert.match(label.bio, /^On this project since \w+ 2026$/);
+  assert.match(label.sig, /^Sana O\. ’26$/, 'signed in the artist\'s hand, a name, an initial and the year');
+  assert.equal(label.heart, 'false');
+  assert.match(label.src, /^\/api\/bongos\/task-visuals\/task-\d+-[0-9a-f]{16}\.jpg$/, 'the dark render in dark mode');
+});
+
+test('in light mode each work hangs its light render, and a theme change re-hangs it', { skip }, async () => {
+  const { ctx, page } = await boot({ theme: 'light' });
+  const w = JSON.parse(FIXTURE).works[0];
+  const light = await page.evaluate(() => document.querySelector('.hg-hang img').getAttribute('src'));
+  await page.evaluate(() => { document.documentElement.dataset.theme = 'dark'; });
+  await page.waitForFunction((d) => document.querySelector('.hg-hang img').getAttribute('src') === d, w.art.dark);
+  await ctx.close();
+  assert.equal(light, w.art.light);
+  assert.notEqual(w.art.light, w.art.dark);
+});
+
+test('the arrows and the arrow keys walk the wall, and stop at its ends', { skip }, async () => {
+  const { ctx, page } = await boot();
+  assert.equal(await page.evaluate(() => document.querySelector('.hg-prev').disabled), true);
+  await page.click('.hg-next');
+  assert.equal((await state(page)).count, `2 of ${N}`);
+  await page.focus('.hg-room');
+  await page.keyboard.press('ArrowRight');
+  await page.keyboard.press('ArrowLeft');
+  await page.keyboard.press('ArrowLeft');
+  const s = await state(page);
+  const hidden = await page.evaluate(() => [...document.querySelectorAll('.hg-hang')].map((h) => h.getAttribute('aria-hidden')).slice(0, 2));
+  await ctx.close();
+  assert.equal(s.count, `1 of ${N}`);
+  assert.deepEqual(hidden, ['false', 'true'], 'only the work in front of you is read out');
+});
+
+test('the label opens closer on a click and closes again; the heart is one fixed size, given and taken back', { skip }, async () => {
+  const { ctx, page } = await boot();
+  const box = () => page.evaluate(() => { const r = document.querySelector('.hg-hang .hg-heart').getBoundingClientRect(); return [Math.round(r.width), Math.round(r.height)]; });
+  const before = await box();
+  await page.click('.hg-hang .hg-text');
+  const reading = await page.evaluate(() => ({ on: document.querySelector('.hg-hang').classList.contains('is-reading'), exp: document.querySelector('.hg-text').getAttribute('aria-expanded'), credit: getComputedStyle(document.querySelector('.hg-credit')).display }));
+  assert.deepEqual(reading, { on: true, exp: 'true', credit: 'block' });
+  assert.deepEqual(await box(), before, 'reading the label closer does not grow the heart');
+  const id = await page.evaluate(() => document.querySelector('.hg-hang .hg-heart').dataset.id);
+  const hearts = JSON.parse(FIXTURE).works[0].hearts;
+  await page.click('.hg-hang .hg-heart');
+  await page.waitForFunction(() => document.querySelector('.hg-hang .hg-heart').getAttribute('aria-pressed') === 'true');
+  const credit = await page.evaluate(() => document.querySelector('.hg-hang .hg-credit').textContent);
+  assert.match(credit, new RegExp(`Appreciated by ${hearts + 1} builders\\.$`));
+  assert.deepEqual(await box(), before, 'a given heart is the same size');
+  await page.click('.hg-hang .hg-heart');
+  await page.waitForFunction(() => document.querySelector('.hg-hang .hg-heart').getAttribute('aria-pressed') === 'false');
+  await page.click('.hg-hang .hg-text');
+  const closed = await page.evaluate(() => document.querySelector('.hg-hang').classList.contains('is-reading'));
+  const asked = (await state(page)).asked;
+  await ctx.close();
+  assert.equal(closed, false);
+  assert.deepEqual(asked.slice(1), [`PUT /api/bongos/home/gallery/${id}/heart {"on":true}`, `PUT /api/bongos/home/gallery/${id}/heart {"on":false}`]);
+  assert.ok(before[0] >= 24 && before[1] >= 24, 'the heart clears the 24px floor');
+});
+
+test('Latest asks for the wall again in that order', { skip }, async () => {
+  const { ctx, page } = await boot();
+  await page.click('.hg-sort [data-order="latest"]');
+  await page.waitForFunction(() => window.__asked.length === 2);
+  await page.waitForTimeout(50);
+  const s = await state(page);
+  await ctx.close();
+  const latest = JSON.parse(FIXTURE).works.slice().sort((a, b) => b.shipped.localeCompare(a.shipped))[0];
+  assert.equal(s.asked[1], 'GET /api/bongos/home/gallery?order=latest');
+  assert.deepEqual(s.pressed, ['popular:false', 'latest:true']);
+  assert.equal(s.count, `1 of ${N}`, 'the wall starts again at its first work');
+  assert.equal(s.first, Lib.fillHoles(latest.title, {}), 'the newest ship hangs first');
+});
+
+test('full screen (F) is the art alone with its signature and heart; Escape returns', { skip }, async () => {
+  const { ctx, page } = await boot();
+  await page.focus('.hg-room');
+  await page.keyboard.press('f');
+  await page.waitForFunction(() => document.fullscreenElement || document.querySelector('.hg-room.is-fs'));
+  const fs = await page.evaluate(() => {
+    const vis = (s) => { const e = document.querySelector(s); return !!e && getComputedStyle(e).display !== 'none' && e.getBoundingClientRect().width > 0; };
+    return { sig: vis('.hg-hang .hg-sig'), heart: vis('.hg-hang .hg-heart'), text: vis('.hg-hang .hg-text'), vinyl: vis('.hg-vinyl'), cap: vis('.hg-cap') };
+  });
+  await page.keyboard.press('Escape');
+  await page.waitForFunction(() => !document.fullscreenElement && !document.querySelector('.hg-room.is-fs'));
+  await ctx.close();
+  assert.deepEqual(fs, { sig: true, heart: true, text: false, vinyl: false, cap: true });
+});
+
+test('the full gallery hangs every work at once; a click sits you in front of that one', { skip }, async () => {
+  const { ctx, page } = await boot();
+  await page.click('.hg-way-all');
+  const all = await page.evaluate(() => ({ pieces: document.querySelectorAll('.hg-piece').length, salon: !document.querySelector('.hg-salon').hidden, way: document.querySelector('.hg-way-all').textContent.trim(), said: document.querySelector('.hg-room').getAttribute('aria-label') }));
+  assert.deepEqual(all, { pieces: N, salon: true, way: 'Back to the bench →', said: 'The full gallery: every work at once. Choose one to sit in front of it.' }, 'the room says what is on screen');
+  await page.click('.hg-piece[data-i="3"]');
+  const s = await state(page);
+  const back = await page.evaluate(() => document.querySelector('.hg-salon').hidden);
+  await ctx.close();
+  assert.equal(back, true);
+  assert.equal(s.count, `4 of ${N}`);
+});
+
+test('at phone width the gallery fits: nothing scrolls sideways and every control clears 24px', { skip }, async () => {
+  const { ctx, page } = await boot({ width: 390, height: 844 });
+  const m = await page.evaluate(() => ({
+    over: document.documentElement.scrollWidth - document.documentElement.clientWidth,
+    small: [...document.querySelectorAll('.hg button, .hg a, .hg-text')].filter((e) => e.getBoundingClientRect().width > 0 && !e.closest('[aria-hidden="true"]')).map((e) => { const r = e.getBoundingClientRect(); return [e.className, Math.round(r.width), Math.round(r.height)]; }).filter((x) => x[1] < 24 || x[2] < 24),
+  }));
+  await ctx.close();
+  assert.equal(m.over, 0);
+  assert.deepEqual(m.small, []);
+});
+
+test('Home is the gallery only in Artistry: the city\'s widget switches on the craft and asks for the wall only then', { skip }, async () => {
+  const { ctx, page } = await boot({ city: true });
+  await page.evaluate(() => window.__widget.mount(document.getElementById('home-city')));
+  await page.waitForFunction(() => document.querySelectorAll('.hc-rung').length > 0);
+  const building = await page.evaluate(() => ({ asked: window.__asked.slice(), gallery: getComputedStyle(document.querySelector('.hg')).display, stage: getComputedStyle(document.querySelector('.hc-stage')).display }));
+  assert.deepEqual(building.asked, ['GET /api/bongos/home/city?weeks=10'], 'the builder\'s Home never asks for the wall');
+  assert.equal(building.gallery, 'none');
+  await page.evaluate(() => { document.documentElement.dataset.craft = 'artistry'; document.dispatchEvent(new CustomEvent('otb:craft', { detail: { mode: 'artistry' } })); });
+  await page.waitForFunction(() => document.querySelectorAll('.hg-hang').length > 0);
+  const art = await page.evaluate(() => ({ asked: window.__asked.slice(), gallery: getComputedStyle(document.querySelector('.hg')).display, stage: getComputedStyle(document.querySelector('.hc-stage')).display, hidden: document.getElementById('home-city').hidden }));
+  await page.evaluate(() => { document.documentElement.dataset.craft = 'building'; document.dispatchEvent(new CustomEvent('otb:craft', { detail: { mode: 'building' } })); });
+  const back = await page.evaluate(() => getComputedStyle(document.querySelector('.hc-stage')).display);
+  await ctx.close();
+  assert.deepEqual(art.asked.slice(1), ['GET /api/bongos/home/gallery?order=popular']);
+  assert.equal(art.stage, 'none', 'the city steps aside');
+  assert.notEqual(art.gallery, 'none');
+  assert.equal(art.hidden, false);
+  assert.notEqual(back, 'none', 'and comes back in another craft');
+});

package/tests/home_studio.mjs

@@ -0,0 +1,169 @@
+// tests/home_studio.mjs — the artist's studio behind the gallery (task 1005061, Home v16
+// step 4).
+//
+// Its two reads with no database: the copy-desk half (modules/copy-desk/routes/
+// copy-desk-studio.js composeStudio: the easel, the pages waiting for an artist, the
+// words to tune, all from the Tweak/CopyWrite Flow's own answer) and the lifecycle half
+// (modules/lifecycle/home-gallery.js readStudioWorks: the works the viewer pinned and
+// signed, by the wall's own rule, bounded) against a recording fake pool, and the page's
+// pure words (modules/hall-ui/public/home-studio.js). The real room in a browser is
+// tests/home_studio_widget.mjs.
+//
+// Run:  node tests/home_studio.mjs
+import assert from 'node:assert/strict';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createRequire } from 'node:module';
+import { makeRunner } from './helpers.mjs';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+process.env.NODE_ENV = 'test';
+const G = require(path.join(ROOT, 'modules/lifecycle/home-gallery.js'));
+const Desk = require(path.join(ROOT, 'modules/copy-desk/routes/copy-desk-studio.js'));
+const Lib = require(path.join(ROOT, 'modules/hall-ui/public/home-studio.js'));
+
+const { test, summary } = makeRunner();
+
+const cand = (id, tier, changed, over = {}) => Object.assign({ page_id: id, title: id.split(':')[1], surface: id.split(':')[0], tier, changed_lines: changed, why: tier }, over);
+
+// ---------------------------------------------------------------------------
+// 1. the copy-desk half
+// ---------------------------------------------------------------------------
+
+await test('the easel is the round you hold, opened in the tweak editor', () => {
+  const s = Desk.composeStudio({ next: { resume: { page_id: 'builders:studio', title: 'Studio', surface: 'builders', round: 2 }, recommended: cand('landing:index', 'asked', 0) }, flagRows: [] });
+  assert.deepEqual(s.easel, { held: true, page_id: 'builders:studio', title: 'Studio', place: 'The builders’ hall', round: 2, open: '/tweak-editor?page=builders%3Astudio' });
+});
+
+await test('with nothing held, the easel offers the page the flow recommends next', () => {
+  const s = Desk.composeStudio({ next: { resume: null, recommended: cand('landing:index', 'asked', 0, { why: '2 people asked for it' }) }, flagRows: [] });
+  assert.equal(s.easel.held, false);
+  assert.equal(s.easel.why, '2 people asked for it');
+  assert.equal(Desk.composeStudio({ next: null, flagRows: [] }).easel, null, 'no flow, no easel');
+});
+
+await test('waiting for new inspiration is the pages changed since their last design, most changed first, bounded', () => {
+  const next = { recommended: cand('landing:index', 'asked', 0), alternatives: [
+    cand('builders:goals', 'changed', 3), cand('builders:home', 'untweaked', 0), cand('builders:settings', 'changed', 12),
+    cand('status:index', 'changed', 1), cand('builders:collab', 'changed', 2), cand('landing:privacy', 'changed', 5), cand('builders:atlas', 'tweaked', 0),
+  ] };
+  const s = Desk.composeStudio({ next, flagRows: [] });
+  assert.equal(s.waiting.total, 5, 'an untweaked page is not waiting on a change; a tweaked one with no drift is not either');
+  assert.deepEqual(s.waiting.pages.map((p) => p.page_id), ['builders:settings', 'landing:privacy', 'builders:goals', 'builders:collab']);
+  assert.equal(s.waiting.pages.length, Desk.MAX_WAITING);
+  assert.equal(s.waiting.pages[0].place, 'The builders’ hall');
+});
+
+await test('words to tune are the newest open flags, as text, never more than three', () => {
+  const rows = [1, 2, 3, 4].map((i) => ({ id: i, text_at_flag: i === 2 ? null : `Line ${i}`, reason: `why ${i}`, surface: 'builders', resolution_note: 'x' }));
+  const s = Desk.composeStudio({ next: null, flagRows: rows });
+  assert.equal(s.words.length, Desk.MAX_WORDS);
+  assert.deepEqual(s.words[0], { id: '1', text: 'Line 1', reason: 'why 1', place: 'The builders’ hall' });
+  assert.equal(s.words[1].text, null, 'a whole-surface flag has no line, only its reason');
+});
+
+// ---------------------------------------------------------------------------
+// 2. the lifecycle half: the two shelves of works
+// ---------------------------------------------------------------------------
+
+function fakePool({ table = true } = {}) {
+  const calls = [];
+  return {
+    calls,
+    async query(sql, params) {
+      calls.push({ sql, params });
+      if (/to_regclass/.test(sql)) return { rows: [{ ok: table }] };
+      return { rows: [] };
+    },
+  };
+}
+
+await test('pinned is the viewer\'s hearts, newest first; yours is what the viewer signed, most appreciated first; both by the wall\'s rule', async () => {
+  const pool = fakePool();
+  const out = await G.readStudioWorks({ viewer: { id: 7, rank: 'thetes' } }, { pool, exists: async () => true });
+  const reads = pool.calls.filter((c) => !/to_regclass/.test(c.sql));
+  assert.equal(reads.length, 2);
+  const [pin, yours] = reads;
+  assert.match(pin.sql, /JOIN lifecycle_work_appreciations pin ON pin\.task_id = t\.id AND pin\.builder_id = \$3::bigint/);
+  assert.match(pin.sql, /ORDER BY pin\.at DESC/);
+  assert.match(yours.sql, /AND t\.shipped_by = \$3::bigint/);
+  assert.match(yours.sql, /ORDER BY hearts DESC/);
+  for (const q of reads) {
+    assert.match(q.sql, /LIMIT 6\b/);
+    assert.match(q.sql, /t\.security_sensitive IS NOT TRUE/);
+    assert.match(q.sql, /goal_members/);
+    assert.deepEqual(q.params, [['artist', 'ui'], false, '7'], 'the shelves are the signed-in viewer\'s');
+  }
+  assert.deepEqual(out, { pinned: [], yours: [], easel: null });
+});
+
+await test('the easel\'s page is asked for by its round ref, newest first, one work, and only a well-formed page id', async () => {
+  const pool = fakePool();
+  await G.readStudioWorks({ viewer: { id: 7 }, page: 'builders:studio' }, { pool, exists: async () => true });
+  const q = pool.calls.find((c) => /starts_with\(t\.source_ref, \$4\)/.test(c.sql));
+  assert.ok(q, 'the easel read');
+  assert.match(q.sql, /t\.source = 'page-tweak'/);
+  assert.match(q.sql, /ORDER BY t\.shipped_at DESC, t\.id DESC\s+LIMIT 1/);
+  assert.match(q.sql, /goal_members/, 'by the wall\'s own rule');
+  assert.equal(q.params[3], 'page-tweak/builders:studio/r');
+  for (const bad of ['builders', 'builders:studio/r1', "x:y' OR 1=1", '']) {
+    const p2 = fakePool();
+    await G.readStudioWorks({ viewer: { id: 7 }, page: bad }, { pool: p2, exists: async () => true });
+    assert.ok(!p2.calls.some((c) => /starts_with/.test(c.sql)), `no easel read for ${JSON.stringify(bad)}`);
+  }
+});
+
+await test('with the hearts table absent there is nothing pinned and your works hang with no hearts', async () => {
+  const pool = fakePool({ table: false });
+  await G.readStudioWorks({ viewer: { id: 7 } }, { pool, exists: async () => true });
+  const reads = pool.calls.filter((c) => !/to_regclass/.test(c.sql));
+  assert.equal(reads.length, 1);
+  assert.doesNotMatch(reads[0].sql, /lifecycle_work_appreciations/);
+});
+
+await test('GET /home/studio/works shapes both shelves for the caller', async () => {
+  let asked = null;
+  const row = { id: '9', title: 'Tweak: Studio (builders:studio)', source: 'page-tweak', source_ref: 'page-tweak/builders:studio/r1', light: '/l', dark: '/d', artist_id: '7', display_name: 'Ana', hearts: 4, mine: true, total: 8, shipped_at: '2026-10-01T00:00:00Z' };
+  const h = G.studioWorksHandler({ read: async (a) => { asked = a; return { pinned: [row], yours: [], easel: row }; } });
+  const res = { set() { return res; }, json(b) { res.body = b; return res; } };
+  await h({ builder: { id: 7, rank: 'metic' }, query: { viewer: '1', page: 'builders:studio' } }, res);
+  assert.deepEqual(asked, { viewer: { id: 7, rank: 'metic' }, page: 'builders:studio' });
+  assert.equal(res.body.easel.page, 'builders:studio');
+  assert.equal(res.body.pinned.total, 8);
+  assert.equal(res.body.pinned.works[0].page, 'builders:studio', 'a tweak work knows its page, so the easel can find it');
+  assert.deepEqual(res.body.yours, { total: 0, works: [] });
+});
+
+// ---------------------------------------------------------------------------
+// 3. the room's words (pure)
+// ---------------------------------------------------------------------------
+
+await test('the easel says what is on it and the one way back in', () => {
+  assert.deepEqual(Lib.easelWords({ held: true, title: 'Studio', round: 2, place: 'The builders’ hall' }),
+    { title: 'Studio · round 2', line: 'Your page, waiting for your words · The builders’ hall.', act: 'Pick up where you left off' });
+  assert.equal(Lib.easelWords({ held: true, title: 'Studio', round: 1 }).title, 'Studio');
+  assert.deepEqual(Lib.easelWords({ held: false, title: 'Privacy', why: 'untweaked' }), { title: 'Nothing on your easel', line: 'Next up: Privacy, untweaked.', act: 'Begin Privacy' });
+  assert.equal(Lib.easelWords(null).act, null);
+  assert.equal(Lib.linesChanged(1), '1 line changed');
+  assert.equal(Lib.linesChanged(12), '12 lines changed');
+});
+
+await test('a work on a shelf links to its place on the bench, and the gallery reads that link back', () => {
+  const Gal = require(path.join(ROOT, 'modules/hall-ui/public/home-gallery.js'));
+  assert.equal(Lib.benchPath('1004387'), '/?work=1004387');
+  assert.equal(Lib.benchPath('1 OR 1'), '/');
+  assert.deepEqual(Gal.landing('?work=1004387'), { work: '1004387', all: false });
+  assert.deepEqual(Gal.landing('?gallery=all'), { work: null, all: true });
+  assert.deepEqual(Gal.landing('?work=abc&gallery=allx'), { work: null, all: false });
+});
+
+await test('a studio link goes only to the tweak editor or the copy desk', () => {
+  assert.equal(Lib.hallPath('/tweak-editor?page=builders%3Astudio'), '/tweak-editor?page=builders%3Astudio');
+  assert.equal(Lib.hallPath('/copy-desk'), '/copy-desk');
+  assert.equal(Lib.hallPath('https://evil.example/'), null);
+  assert.equal(Lib.hallPath('javascript:alert(1)'), null);
+  assert.equal(Lib.hallPath('/tweak-editor?page="><x>'), null);
+});
+
+summary();

package/tests/home_studio_widget.mjs

@@ -0,0 +1,157 @@
+// tests/home_studio_widget.mjs — the artist's studio, the real shelves in a browser
+// (task 1005061, Home v16 step 4).
+//
+// Runs home-gallery.js (the label words and picture rule) and home-studio.js on a page
+// that carries the /studio page's host, with the reads stubbed by the hall-preview
+// fixtures: the shelves mount by themselves and ask the copy-desk read, then the works
+// read for the easel's page; the easel shows that page as it hangs and links into the
+// tweak editor; the waiting pages, the flagged words and both shelves of works are
+// drawn, each work linking back to its place on the bench; the doors lead to the bench
+// and the full gallery; each shelf's empty state says so in words; without the copy
+// desk its shelves say so; at phone width nothing scrolls sideways. And the gallery
+// arriving from those links: ?work=<id> sits you in front of it, ?gallery=all opens the
+// salon. Skips where no system Edge or Chrome is installed.
+//
+// Run:  node --test tests/home_studio_widget.mjs
+import assert from 'node:assert/strict';
+import { test, after } from 'node:test';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const lib = require(path.join(ROOT, 'modules', 'ui-design', 'kit', 'lib.js'));
+const pub = (f) => fs.readFileSync(path.join(ROOT, 'modules', 'hall-ui', 'public', f), 'utf8');
+const fx = (f) => fs.readFileSync(path.join(ROOT, 'scripts', 'hall-preview', 'fixtures', f), 'utf8');
+const CSS = pub('home-city.css') + pub('home-gallery.css') + pub('home-studio.css');
+const GALLERY = fx('home__gallery.json');
+const DESK = fx('copy-desk__studio.json');
+const WORKS = fx('home__studio__works.json');
+const EMPTY_DESK = JSON.stringify({ easel: null, waiting: { total: 0, pages: [] }, words: [] });
+const EMPTY_WORKS = JSON.stringify({ pinned: { total: 0, works: [] }, yours: { total: 0, works: [] }, easel: null });
+
+let browser = null;
+try { browser = await lib.launchBrowser(); } catch (e) { if (!(e instanceof lib.NoBrowserError)) throw e; }
+after(() => browser && browser.close());
+const skip = !browser && 'no system Edge or Chrome';
+
+const stubs = ({ desk, works }) => `
+  window.__asked = [];
+  window.BongosClient = { createClient: () => ({ request: async (m, p) => {
+    window.__asked.push(m + ' ' + p);
+    if (p.startsWith('/api/bongos/home/gallery?')) return { ok: true, status: 200, data: ${GALLERY} };
+    if (p === '/api/bongos/copy-desk/studio') return ${desk ? `{ ok: true, status: 200, data: ${desk} }` : '{ ok: false, status: 404, data: null }'};
+    if (p.startsWith('/api/bongos/home/studio/works')) return { ok: true, status: 200, data: ${works} };
+    return { ok: false, status: 404, data: null };
+  } }) };`;
+
+// The studio page is served at a real http origin so its links resolve like the hall's.
+async function boot({ width = 1440, desk = DESK, works = WORKS } = {}) {
+  const ctx = await browser.newContext({ viewport: { width, height: 900 }, reducedMotion: 'reduce' });
+  const page = await ctx.newPage();
+  await page.route('http://hall.test/**', (r) => r.fulfill({ contentType: 'text/html', body: `<!doctype html><html data-theme="dark"><head><style>${CSS}</style></head><body><section class="hs-page" id="studio-shelves"></section></body></html>` }));
+  await page.goto('http://hall.test/studio');
+  await page.addScriptTag({ content: stubs({ desk, works }) });
+  await page.addScriptTag({ content: pub('home-gallery.js') });
+  await page.addScriptTag({ content: pub('home-studio.js') });
+  await page.waitForFunction(() => document.querySelector('.hs-pinned') && document.querySelector('.hs-pinned').children.length > 0);
+  return { ctx, page };
+}
+
+const room = (page) => page.evaluate(() => ({
+  asked: window.__asked.slice(),
+  easel: document.querySelector('.hs-what b').textContent,
+  pill: [document.querySelector('.hs-pill').textContent, document.querySelector('.hs-pill').getAttribute('href'), document.querySelector('.hs-pill').hidden],
+  art: (document.querySelector('.hs-art img') || {}).src || null,
+  waiting: [...document.querySelectorAll('.hs-waiting .hs-row')].map((r) => [r.querySelector('b').textContent, r.querySelector('.hs-dot').textContent, r.getAttribute('href')]),
+  words: [...document.querySelectorAll('.hs-words .hs-row q')].map((q) => q.textContent),
+  pinned: [...document.querySelectorAll('.hs-pinned .hs-work')].map((b) => [b.querySelector('.hs-sub').textContent, b.getAttribute('href')]),
+  yours: [...document.querySelectorAll('.hs-yours .hs-work')].map((b) => b.querySelector('.hs-sub').textContent),
+  quiet: [...document.querySelectorAll('.hs-quiet')].map((p) => p.textContent),
+  doors: [...document.querySelectorAll('.hs-ways a')].map((a) => a.getAttribute('href')),
+}));
+
+test('the shelves mount on the studio page: the copy-desk read, then the works read for the easel\'s page', { skip }, async () => {
+  const { ctx, page } = await boot();
+  const s = await room(page);
+  const desk = JSON.parse(DESK), works = JSON.parse(WORKS);
+  await ctx.close();
+  assert.deepEqual(s.asked, ['GET /api/bongos/copy-desk/studio', `GET /api/bongos/home/studio/works?page=${encodeURIComponent(desk.easel.page_id)}`]);
+  assert.equal(s.easel, `${desk.easel.title} · round ${desk.easel.round}`);
+  assert.deepEqual(s.pill, ['Pick up where you left off', desk.easel.open, false]);
+  assert.match(s.art || '', new RegExp(works.easel.art.dark.replace(/[.?]/g, '\\$&') + '$'), 'the easel shows the page as it hangs on the wall');
+  assert.deepEqual(s.waiting.map((w) => w[0]), desk.waiting.pages.map((p) => p.title));
+  assert.equal(s.waiting[0][1], String(desk.waiting.pages[0].changed_lines));
+  assert.equal(s.waiting[0][2], desk.waiting.pages[0].open, 'each waiting page opens where its words are worked');
+  assert.deepEqual(s.words, desk.words.map((w) => w.text));
+  assert.deepEqual(s.pinned.map((p) => p[0]), works.pinned.works.map(() => 'You appreciated this'));
+  assert.deepEqual(s.pinned.map((p) => p[1]), works.pinned.works.map((w) => `/?work=${w.id}`), 'a pinned work links to its place on the bench');
+  assert.deepEqual(s.yours, works.yours.works.map((w) => String(w.hearts)), 'your works carry their heart counts');
+  assert.deepEqual(s.doors, ['/', '/?gallery=all']);
+});
+
+test('every shelf says in words when it is empty, and an empty easel offers no way in', { skip }, async () => {
+  const { ctx, page } = await boot({ desk: EMPTY_DESK, works: EMPTY_WORKS });
+  const s = await room(page);
+  await ctx.close();
+  assert.deepEqual(s.asked, ['GET /api/bongos/copy-desk/studio', 'GET /api/bongos/home/studio/works'], 'no easel page, no page asked for');
+  assert.equal(s.easel, 'Nothing on your easel');
+  assert.equal(s.pill[2], true);
+  assert.equal(s.art, null);
+  assert.deepEqual(s.quiet, [
+    'Nothing is waiting. Every page’s words match its last design.',
+    'No words are flagged. The copy desk is quiet.',
+    'Nothing pinned yet. A heart on the bench pins a work here.',
+    'Nothing of yours hangs in the collection yet.',
+  ]);
+});
+
+test('without the copy desk its two shelves say so, and the works still hang', { skip }, async () => {
+  const { ctx, page } = await boot({ desk: null });
+  const s = await room(page);
+  const desk = await page.evaluate(() => document.querySelector('.hs-desk').hidden);
+  await ctx.close();
+  assert.equal(s.easel, 'Nothing on your easel');
+  assert.deepEqual(s.quiet, ['The copy desk is not switched on in this project.', 'The copy desk is not switched on in this project.']);
+  assert.equal(desk, true);
+  assert.ok(s.yours.length > 0);
+});
+
+test('at phone width the studio fits: nothing scrolls sideways and every control clears 24px', { skip }, async () => {
+  const { ctx, page } = await boot({ width: 390 });
+  const m = await page.evaluate(() => ({
+    over: document.documentElement.scrollWidth - document.documentElement.clientWidth,
+    small: [...document.querySelectorAll('.hs button, .hs a')].filter((e) => !e.hidden && e.getBoundingClientRect().width > 0).map((e) => { const r = e.getBoundingClientRect(); return [e.className, Math.round(r.width), Math.round(r.height)]; }).filter((x) => x[1] < 24 || x[2] < 24),
+  }));
+  await ctx.close();
+  assert.equal(m.over, 0);
+  assert.deepEqual(m.small, []);
+});
+
+// ---- the gallery, arriving from the studio's links ----
+async function arrive(search) {
+  const ctx = await browser.newContext({ viewport: { width: 1440, height: 900 }, reducedMotion: 'reduce' });
+  const page = await ctx.newPage();
+  await page.route('http://hall.test/**', (r) => r.fulfill({ contentType: 'text/html', body: `<!doctype html><html data-theme="dark"><head><style>${CSS}</style></head><body><section id="home-city" class="scroll home-city hc--gallery"></section></body></html>` }));
+  await page.goto('http://hall.test/' + search);
+  await page.addScriptTag({ content: stubs({ desk: DESK, works: WORKS }) });
+  await page.addScriptTag({ content: pub('home-gallery.js') });
+  await page.evaluate(() => window.OTBHomeGallery.attach(document.getElementById('home-city')).show(true));
+  await page.waitForFunction(() => document.querySelectorAll('.hg-hang').length > 0);
+  const out = await page.evaluate(() => ({ count: document.querySelector('.hg-count').textContent, salon: !document.querySelector('.hg-salon').hidden, url: location.pathname + location.search }));
+  await ctx.close();
+  return out;
+}
+
+test('the gallery opens where the studio sent you: a work on the bench, or the full gallery; then the address is plain again', { skip }, async () => {
+  const works = JSON.parse(GALLERY).works;
+  const id = works[4].id;
+  const sat = await arrive(`?work=${id}`);
+  assert.deepEqual(sat, { count: `5 of ${works.length}`, salon: false, url: '/' });
+  const all = await arrive('?gallery=all');
+  assert.deepEqual(all, { count: `1 of ${works.length}`, salon: true, url: '/' });
+  const plain = await arrive('');
+  assert.deepEqual(plain, { count: `1 of ${works.length}`, salon: false, url: '/' });
+});