@bongos/core 1.24.26 → 1.24.28

package/tests/loading_mark.mjs

@@ -0,0 +1,203 @@
+// tests/loading_mark.mjs — the Bongos-mark loader on the apex pages and the status page
+// (task 1005053, goal 1000095; the hall's own is task 1005043).
+//
+// Owner ask, 2026-11-03: a smooth load screen with the Bongos logo anywhere the
+// software waits for data, in the spirit of monday.com's Vibe data loaders. The
+// apex pages (cosmos.css) and the status page (its own sheet) each carry the same
+// CSS component, .loading-mark, in their own tokens; a page opts in by putting the
+// class on the placeholder it already had, whose words stay as the caption. These
+// cases read the real sheets and pages, per surface: the loader keeps DESIGN.md's
+// motion and colour rules, its rest frame is the logo, and no waiting placeholder
+// is left as a bare line of text.
+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 LANDING = path.join(ROOT, 'modules', 'public-landing', 'public');
+const STATUS = path.join(ROOT, 'modules', 'status-ui', 'public');
+const read = (dir, f) => fs.readFileSync(path.join(dir, f), 'utf8').replace(/\r\n/g, '\n');
+
+const COSMOS = read(LANDING, 'assets/cosmos.css');
+const STATUS_CSS = read(STATUS, 'style.css');
+const APEX_PAGES = ['account', 'community', 'connections', 'guild', 'invitations', 'projects'];
+
+// The loader's section of a sheet: from its banner to the last of its keyframes.
+function section(css, banner) {
+  const start = css.indexOf(banner);
+  assert.ok(start > -1, `the loader's banner is in the sheet: ${banner}`);
+  const end = css.indexOf('@keyframes loading-mark-breathe', start);
+  assert.ok(end > start, 'the loader section ends on its breath');
+  return css.slice(start, css.indexOf('}', css.indexOf('}', end) + 1) + 1);
+}
+const SURFACES = {
+  apex: { css: COSMOS, loader: section(COSMOS, '/* ── the loader (task 1005053') },
+  status: { css: STATUS_CSS, loader: section(STATUS_CSS, '/* ---------- The loader (task 1005053') },
+};
+const flat = (s) => s.replace(/\/\*[\s\S]*?\*\//g, '').replace(/\s+/g, ' ');
+const masksOf = (css) => [...css.matchAll(/url\("data:image\/svg\+xml,([^"]+)"\)/g)].map((m) => decodeURIComponent(m[1]));
+function keyframes(css, name) {
+  const m = css.match(new RegExp(`@keyframes ${name} ?\\{`));
+  assert.ok(m, `@keyframes ${name} exists`);
+  let depth = 1, i = m.index + m[0].length;
+  for (; i < css.length && depth; i++) depth += css[i] === '{' ? 1 : css[i] === '}' ? -1 : 0;
+  return css.slice(m.index + m[0].length, i - 1);
+}
+
+test('the apex loader is the bar\'s own Bongos mark, and the status loader is the same mark', () => {
+  // The apex bar draws the mark inline (account.html's .bongosMark); the loader's
+  // two masks carry exactly its arc, core and dot, so the loader IS the logo.
+  const bar = read(LANDING, 'account.html');
+  const arc = bar.match(/<path class="mr" d="([^"]+)"/)[1];
+  assert.match(bar, /<circle class="mp" cx="100" cy="100" r="55"/);
+  assert.match(bar, /<circle cx="156" cy="46" r="12" style="fill:var\(--accent\)"\/>/);
+  const [ring, dot] = masksOf(SURFACES.apex.loader);
+  assert.ok(ring.includes(`d='${arc}'`), 'the ring is the bar mark\'s arc');
+  assert.ok(ring.includes("<circle cx='100' cy='100' r='55'/>"), 'the core is the bar mark\'s core');
+  assert.ok(dot.includes("<circle cx='156' cy='46' r='12'/>"), 'the dot is the bar mark\'s dot');
+  // The status page has no Bongos mark of its own: its loader carries the apex's two
+  // masks byte for byte, so the two surfaces cannot drift into two logos.
+  assert.deepEqual(masksOf(SURFACES.status.loader), masksOf(SURFACES.apex.loader));
+});
+
+for (const [name, { css, loader }] of Object.entries(SURFACES)) {
+  test(`${name}: it moves in CSS only, on transform and filter only, and rests on the logo`, () => {
+    for (const frame of ['loading-mark-arrive', 'loading-mark-turn', 'loading-mark-breathe']) {
+      const body = keyframes(css, frame);
+      const props = [...body.matchAll(/([a-z-]+)\s*:/g)].map((m) => m[1]);
+      assert.ok(props.length, `${frame} animates something`);
+      for (const p of props) assert.ok(['transform', 'filter'].includes(p), `${frame} animates ${p}, not transform or filter`);
+    }
+    // The turn has no `from`, so 0deg (the logo's own pose, the dot top right) is where
+    // it starts and where the Kill Switch leaves it; the arrival and the breath have no
+    // `to`, so their resting value is the element as styled, fully shown.
+    assert.match(keyframes(css, 'loading-mark-turn'), /^\s*to ?\{ ?transform: ?rotate\(1turn\); ?\}\s*$/);
+    assert.match(keyframes(css, 'loading-mark-arrive'), /^\s*from ?\{/);
+    assert.match(keyframes(css, 'loading-mark-breathe'), /^\s*from ?\{/);
+    // It arrives 240ms late, so a read that answers faster never shows it.
+    assert.match(flat(loader), /\.loading-mark ?\{[^}]*animation: ?loading-mark-arrive 500ms cubic-bezier\(\.16, ?1, ?\.3, ?1\) 240ms both;/);
+    // The Kill Switch stops every animation, the pseudo-elements included.
+    assert.match(flat(css), /@media \(prefers-reduced-motion: ?reduce\) ?\{ ?\*, ?\*::before, ?\*::after ?\{ ?animation: ?none !important; ?transition: ?none !important; ?\} ?\}/);
+  });
+
+  test(`${name}: every colour is a token; the black in the masks is alpha, not paint`, () => {
+    const css = flat(loader);
+    assert.doesNotMatch(css, /#[0-9a-fA-F]{3,8}\b|rgba?\(|hsla?\(/, 'no colour literal');
+    const paints = [...css.matchAll(/(?:background|color): ?([^;]+);/g)].map((m) => m[1].trim());
+    assert.equal(paints.length, 3, 'the ink, the dot and the caption are painted');
+    for (const p of paints) assert.match(p, /^(var\(--[a-z-]+\)|color-mix\(in srgb, ?var\(--ink\) 30%, ?var\(--bg-card\)\))$/, `${p} is a token or a mix of one`);
+    // The one accent is the dot: the live thing on a waiting page (the One Warm Thing Rule).
+    assert.equal((css.match(/var\(--accent\)/g) || []).length, 1, 'the accent paints the dot alone');
+    const masks = masksOf(loader);
+    assert.equal(masks.length, 2, 'two masks: the ring and core, and the dot');
+    for (const m of masks) assert.doesNotMatch(m.replace(/stroke='black'|fill='none'/g, ''), /fill='|stroke='|#/, 'a mask carries no colour of its own');
+  });
+
+  test(`${name}: the dot shares the ring's grid cell, so no page padding can knock it off`, () => {
+    const css = flat(loader);
+    assert.match(css, /\.loading-mark ?\{[^}]*display: ?grid;/);
+    assert.match(css, /\.loading-mark::before, ?\.loading-mark::after ?\{[^}]*grid-area: ?1 ?\/ ?1;/);
+    assert.doesNotMatch(css, /position: ?absolute|top: ?|left: ?/, 'nothing is positioned by hand');
+  });
+}
+
+test('apex: three sizes, and a hidden placeholder stays hidden', () => {
+  const css = flat(SURFACES.apex.loader);
+  assert.match(css, /\.loading-mark--page ?\{[^}]*--lm-size: ?64px;/);
+  assert.match(css, /\.loading-mark--inline ?\{[^}]*--lm-size: ?16px;[^}]*grid-template-columns: ?var\(--lm-size\) minmax\(0, ?1fr\);/);
+  // The loader is display: grid, which outranks the browser's own [hidden]; the
+  // apex pages put a placeholder away with .hidden, so cosmos's rule must win.
+  assert.match(COSMOS, /\[hidden\]\{display:none !important;\}/);
+});
+
+test('apex: every waiting placeholder wears the loader, in the markup and as the scripts write it', () => {
+  // A status line rewritten IN PLACE (its words become the answer) keeps its plain
+  // words: the loader belongs to a placeholder that is hidden or replaced when the
+  // data lands. Each one is named here with why.
+  const IN_PLACE = new Set([
+    "community.html:say('Searching…')",                                   // the search's status line, rewritten with the count
+    "projects.html:hint('h-renderKey', 'Checking with Render…')",         // the Render key's hint, rewritten with the answer
+    "projects.html:say('Reading your organisations from GitHub…')",       // the org picker's status line
+    "projects.html:say('Checking with GitHub…')",                         // the same line
+    "projects.html:inviteSay(id, 'Finding your project’s invite page…'", // the invite box's message, after a press
+    "projects.html:inviteSay(id, 'Finding the guild’s members…'",        // the same, for a guild
+  ]);
+  const WAIT_WORD = '(?:Loading|Reading|Opening|Checking|Finding|Searching|Looking|Fetching)';
+  const ELEMENT = new RegExp(`<(p|div|li|span|td)\\b([^>]*)>\\s*${WAIT_WORD}\\b[^<]*…\\s*<\\/\\1>`, 'g');
+  const LITERAL = new RegExp(`[a-zA-Z]+\\((?:id, )?'${WAIT_WORD}[^']*…'`, 'g');
+  const misses = [];
+  for (const page of APEX_PAGES) {
+    const html = read(LANDING, `${page}.html`);
+    for (const m of html.matchAll(ELEMENT)) {
+      if (!/\bloading-mark\b/.test(m[2])) misses.push(`${page}.html: ${m[0].slice(0, 100)}`);
+    }
+    for (const line of html.split('\n')) {
+      for (const m of line.matchAll(LITERAL)) {
+        if (/loading-mark/.test(line) || /pickNote\('[^']*', true\)/.test(line)) continue;
+        const key = `${page}.html:${m[0]}`;
+        if (!IN_PLACE.has(key) && !IN_PLACE.has(`${key})`)) misses.push(key);
+      }
+    }
+  }
+  assert.deepEqual(misses, [], 'every waiting placeholder wears the loader');
+});
+
+test('apex: each page waits with the size that fits it', () => {
+  const html = Object.fromEntries(APEX_PAGES.map((p) => [p, read(LANDING, `${p}.html`)]));
+  // a page with nothing else to show yet: the page size
+  for (const [page, words] of [['account', 'Reading your account…'], ['connections', 'Reading your connections…'], ['guild', 'Reading this guild…'], ['invitations', 'Reading your invitations…']]) {
+    assert.ok(html[page].includes(`<p class="loading loading-mark loading-mark--page" id="loading" role="status">${words}</p>`), `${page} waits on the page loader`);
+  }
+  assert.ok(html.projects.includes('<div class="loading loading-mark loading-mark--page" id="loading" role="status">Reading your projects…</div>'));
+  assert.ok(html.projects.includes('<div class="loading loading-mark loading-mark--page" id="mLoading" role="status">Reading the project…</div>'));
+  // a section of a page: the default
+  for (const id of ['homeLoading', 'boardLoading', 'weekLoading', 'recruitLoading']) {
+    assert.match(html.community, new RegExp(`<p class="commMsg loading-mark" id="${id}" role="status">`), `community's ${id}`);
+  }
+  // a line in a band or a list: inline. The manage page's thirteen sections each wait on
+  // their own read, so a mark the height of the line keeps the page from jumping.
+  assert.equal((html.projects.match(/><p class="finePrint loading-mark loading-mark--inline" role="status">(?:Reading the project…|Reading the project’s settings…|Checking the repository on GitHub…)<\/p><\/div>/g) || []).length, 14);
+  assert.ok(html.account.includes('<p class="aWhat loading-mark loading-mark--inline" id="waysLoading" role="status">'));
+  assert.ok(html.account.includes('<p class="aWhat loading-mark loading-mark--inline" id="buildingLoading" role="status">'));
+  assert.ok(html.projects.includes('<div id="ghBusy" class="hint loading-mark loading-mark--inline" role="status" hidden>'));
+  // the scripts write them back the same way, and the picker's first open wears it too
+  for (const call of ['repoVisMsg(', 'visMsg(', 'joinMsg(', 'doorMsg(', 'envMsg(']) {
+    assert.ok(html.projects.includes(`${call}'<p class="finePrint loading-mark loading-mark--inline" role="status">`), `${call} writes the loader`);
+  }
+  for (const call of ['visRuns(', 'joinRuns(']) {
+    assert.ok(html.projects.includes(`${call}'<span class="loading-mark loading-mark--inline" role="status">Checking what the project is running…</span>');`), `${call} writes the loader`);
+  }
+  assert.match(html.projects, /wait\.className = 'finePrint loading-mark loading-mark--inline'; wait\.setAttribute\('role', 'status'\);/);
+  assert.match(html.invitations, /li\.className = 'joinList__note' \+ \(waiting \? ' loading-mark loading-mark--inline' : ''\);/);
+});
+
+test('status: its two waiting tablets wear the loader, and a failed or empty read stops it', () => {
+  const html = read(STATUS, 'index.html');
+  assert.ok(html.includes('<div id="versions" class="versions">\n      <p class="empty loading-mark" role="status">The masons are at their tools…</p>'));
+  assert.ok(html.includes('<div id="world-snapshot" class="world-snapshot">\n      <p class="empty loading-mark" role="status">The cartographers are still at their survey…</p>'));
+  // the header's "Tablet being consulted…" is rewritten in place before any read
+  // starts (stampRefreshTime), so it is never a wait and keeps its plain words
+  assert.match(html, /<span class="herm__updated" id="last-updated">Tablet being consulted…<\/span>/);
+  // The Kill Switch is the last thing in the status sheet, so nothing can outrank it.
+  assert.match(STATUS_CSS.trimEnd(), /@media \(prefers-reduced-motion: reduce\) \{\n {2}\*, \*::before, \*::after \{ animation: none !important; transition: none !important; \}\n\}$/);
+
+  const js = read(STATUS, 'status.js');
+  // the three ways a tablet can end its wait without data each stop the loader
+  assert.match(js, /\} catch \(_\) \{\n {4}stopWaiting\(els\.worldSnapshot\);\n {4}return;\n {2}\}/);
+  assert.match(js, /if \(snapshots\.length === 0\) \{ stopWaiting\(els\.worldSnapshot\); return; \}/);
+  assert.match(js, /loadVersions\(\)\.catch\(\(e\) => \{ stopWaiting\(els\.versions\); console\.error\('versions', e\); \}\)/);
+  // ...and stopWaiting itself, run: it takes the class off and leaves the words alone.
+  const src = js.match(/function stopWaiting\(el\) \{[\s\S]*?\n\}/)[0];
+  const removed = [];
+  const wait = { textContent: 'The masons are at their tools…', classList: { remove: (c) => removed.push(c) } };
+  const host = { querySelectorAll: (sel) => (sel === '.loading-mark' ? [wait] : []) };
+  const ctx = vm.createContext({});
+  vm.runInContext(`${src}; this.stopWaiting = stopWaiting;`, ctx);
+  ctx.stopWaiting(host);
+  ctx.stopWaiting(null);
+  assert.deepEqual(removed, ['loading-mark']);
+  assert.equal(wait.textContent, 'The masons are at their tools…');
+});

package/tests/nav_permission_atoms.mjs

@@ -93,8 +93,9 @@ test('the hall-preview fixture carries every atom /me resolves', () => {
 // says a held core version was tried and rolled back; task 1004731: the one-time
 // "Upgraded to core X" notice after a move; task 1004826: Standing is Accomplishments;
 // task 1004846: the new logo (its bump landed late, in task 1004852); task 1004938: the
-// Market Watch settings nav item and its fuel glyph.
-const SHELL_SHA = '1a23b1cf13567eff';
+// Market Watch settings nav item and its fuel glyph; task 1005041: the Update pill replaced the
+// core-update banner.
+const SHELL_SHA = '9e32caf8aa17dd36';
 
 test('shell.js has not changed without its cache-bust being bumped', () => {
   const actual = crypto.createHash('sha256').update(SHELL).digest('hex').slice(0, 16);

package/tests/software_update.mjs

@@ -345,11 +345,15 @@ test('read only when its group opens — most visits to Settings are for somethi
 
 const answerWith = (over) => ok({ ...FIXTURE, ...over, update: { ...FIXTURE.update, ...(over.update || {}) } });
 
+// task 1005041: the button runs the Update pill's in-place flow, so it no longer reads as a
+// trip off-site; its href stays the hub's door only for a page whose pill script did not load,
+// and the hint names the hub whose small window opens for a moment.
 test('a hosted project\'s button names the hub it opens; a self-hosted one names the command', async () => {
   const hub = bootPanel(() => answerWith({ door: { kind: 'hub', url: 'https://cloudbongos.com/deploy?project=mercury' } }));
   await hub.settle();
-  assert.match(hub.body(), /href="https:\/\/cloudbongos\.com\/deploy\?project=mercury">Update to [\d.]+ ↗</);
-  assert.match(hub.body(), /on cloudbongos\.com:/);
+  assert.match(hub.body(), /href="https:\/\/cloudbongos\.com\/deploy\?project=mercury">Update to [\d.]+</);
+  assert.doesNotMatch(hub.body(), /↗/, 'it updates in place; it is not a link off-site any more');
+  assert.match(hub.body(), /A small window from cloudbongos\.com opens for a moment/);
 
   const cli = bootPanel(() => answerWith({ door: { kind: 'cli', url: null } }));
   await cli.settle();

package/tests/speciality_offer_ui.mjs

@@ -1,27 +1,30 @@
-// tests/speciality_offer_ui.mjs — a speciality's OWNER chooses what it offers,
-// from the hall (task 1004404; ADR 0310 §1).
+// tests/speciality_offer_ui.mjs — the OWNER's side of the speciality tools:
+// creating one, training it, and choosing what it offers (task 1004404; ADR 0310
+// §1; on My agents too since task 1005052).
 //
-// Before this only the API could set a speciality's offered skills, so nothing
-// made in the hall offered any and the adoption walkthrough never appeared. These
-// pin that the owner can choose on create AND afterwards, that each choice shows
-// the skill's plain description, that only installed skills are choices, and that
-// a skill removed since is named rather than silently kept.
+// Before task 1004404 only the API could set a speciality's offered skills, so
+// nothing made in the hall offered any and the adoption walkthrough never
+// appeared. These pin that the owner can choose on create AND afterwards, that
+// each choice shows the skill's plain description, that only installed skills are
+// choices, and that a skill removed since is named rather than silently kept —
+// and that training adds a document in one request, refused inline when a field
+// is empty.
 //
-// Like tests/speciality_walkthrough_ui.mjs this EXECUTES the real
-// modules/hall-ui/public/settings-specialities.js in a vm under a minimal DOM
-// stub against a fake API, and drives the delegated handlers the page wires.
+// TWO PAGES, ONE COMPONENT (task 1005052). modules/hall-ui/public/speciality-tools.js
+// is mounted by Settings and by My agents, and it renders its own create form, so
+// neither page carries a second copy of that markup. Every case runs once per
+// page, booted on THAT page's own markup (tests/helpers.mjs bootSpecialityTools),
+// so a host lost from either page fails that page's run.
 //
 // Run:  node tests/speciality_offer_ui.mjs
 import assert from 'node:assert/strict';
 import fs from 'node:fs';
 import path from 'node:path';
-import vm from 'node:vm';
 import { fileURLToPath } from 'node:url';
-import { makeRunner } from './helpers.mjs';
+import { makeRunner, bootSpecialityTools, SPECIALITY_PAGES } from './helpers.mjs';
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
-const SRC = fs.readFileSync(path.join(ROOT, 'modules/hall-ui/public/settings-specialities.js'), 'utf8');
-const HTML = fs.readFileSync(path.join(ROOT, 'modules/hall-ui/public/settings.html'), 'utf8');
+const SRC = fs.readFileSync(path.join(ROOT, 'modules/hall-ui/public/speciality-tools.js'), 'utf8');
 const { test, summary } = makeRunner();
 
 const INSTALLED = [
@@ -33,153 +36,183 @@ const INSTALLED = [
 const mine = (over = {}) => ({ id: 12, name: 'Pricing', discipline: 'engineer', summary: '', contract_md: '', visibility: 'private', adoptable: true, mine: true, skills: ['recall', 'retired-skill'], ...over });
 const theirs = (over = {}) => ({ id: 9, name: 'Economics', discipline: 'ideator', summary: '', contract_md: '', visibility: 'public', adoptable: true, mine: false, skills: ['recall'], ...over });
 
-// The checked boxes a form would submit, read off the rendered markup.
+// The ticked boxes in rendered markup.
 const checkedIn = (html) => [...html.matchAll(/<input type="checkbox" name="skill" value="([^"]+)" checked/g)].map((m) => m[1]);
-const fakeForm = (dataset, values) => ({
-  dataset,
-  querySelectorAll: (sel) => (sel === 'input[name="skill"]:checked' ? values.map((value) => ({ value })) : []),
-});
 
-async function boot({ catalog = [mine(), theirs()] } = {}) {
-  const requests = [];
-  const toasts = [];
-  const els = new Map();
-  const handlers = new Map();
-  const makeEl = (id) => ({
-    id, hidden: id === 'specialities-scroll', innerHTML: '', textContent: '', elements: {}, dataset: {}, open: false,
-    addEventListener(type, fn) { handlers.set(`${id}:${type}`, fn); },
-  });
-  for (const id of ['specialities-scroll', 'specialities-rows', 'speciality-suggestions', 'specialities-status', 'speciality-create', 'speciality-create-offer', 'speciality-create-skills']) els.set(id, makeEl(id));
-  // The create form's fields, as settings.html declares them.
-  const create = els.get('speciality-create');
-  const field = (value) => ({ value, addEventListener() {} });
-  create.elements = { name: field(''), discipline: field(''), summary: field(''), contract_md: field(''), visibility: field('private'), sellable: { checked: false, disabled: false, addEventListener() {} } };
-  create.reset = () => { create.elements.name.value = ''; };
-  create.querySelectorAll = () => [];
-
-  const fetch = async (url, opts = {}) => {
-    const method = opts.method || 'GET';
-    const p = url.replace('/api/bongos', '');
-    requests.push({ method, path: p, body: opts.body ? JSON.parse(opts.body) : undefined });
-    let body = {};
-    if (method === 'GET' && p === '/specialities') body = { specialities: catalog };
-    else if (method === 'GET' && p === '/me/specialities') body = { adoptions: [] };
-    else if (method === 'GET' && p === '/specialities/offered') body = { suggestions: [] };
-    else if (method === 'GET' && p === '/specialities/installed-skills') body = { skills: INSTALLED };
-    else if (method === 'PATCH') body = { speciality: { id: 12 } };
-    else if (method === 'POST' && p === '/specialities') body = { speciality: { id: 13 } };
-    return { ok: true, status: 200, json: async () => body };
-  };
-
-  const document = { readyState: 'complete', getElementById: (id) => els.get(id) || null, addEventListener() {}, querySelector: () => null };
-  const window = {
-    OTB: {
-      escapeHtml: (s) => String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;'),
-      $: () => null, toast: (m) => toasts.push(m), roleAxisLabel: () => 'Role',
-    },
-    location: { assign() {} },
-  };
-  vm.runInNewContext(SRC, { window, document, fetch, JSON, Promise, Map, Set, String, Number, Array, Object, Math, RegExp, console });
-  const settle = async () => { for (let i = 0; i < 8; i++) await new Promise((r) => setTimeout(r, 0)); };
-  await settle();
-
-  const rows = els.get('specialities-rows');
-  async function click(act, id) {
-    const btn = { dataset: { act, id: String(id) } };
-    handlers.get('specialities-rows:click')({ target: { closest: (sel) => (sel === 'button[data-act]' ? btn : null) } });
-    await settle();
-  }
-  async function submitOffer(id, values) {
-    const form = fakeForm({ id: String(id) }, values);
-    handlers.get('specialities-rows:submit')({ target: { closest: (sel) => (sel === 'form.speciality-offer' ? form : null) }, preventDefault() {} });
-    await settle();
-  }
-  return { els, rows, requests, toasts, click, submitOffer, handlers, create, settle };
+async function boot(page, { catalog = [mine(), theirs()], ...rest } = {}) {
+  const h = bootSpecialityTools({ page, catalog, installed: INSTALLED, ...rest });
+  await h.ready();
+  return h;
 }
-
-const writes = (h) => h.requests.filter((r) => r.method !== 'GET');
+const ROWS = '#specialities-rows';
+const OFFER = `${ROWS} form.speciality-offer`;
+const writes = (h) => h.writes();
 const installedReads = (h) => h.requests.filter((r) => r.path === '/specialities/installed-skills').length;
+// every element id the component looks up
+const HOSTS = [...new Set([...SRC.matchAll(/\bel\('([a-z-]+)'\)/g)].map((m) => m[1]))];
 
-await test('only a speciality you own has an "Offered skills" control', async () => {
-  const h = await boot();
-  const buttons = [...h.rows.innerHTML.matchAll(/data-act="offer" data-id="(\d+)"/g)].map((m) => m[1]);
-  assert.deepEqual(buttons, ['12']);
-});
-
-await test('opening it lists every installed skill with its plain description and cost, the current offer ticked', async () => {
-  const h = await boot();
-  assert.equal(installedReads(h), 0, 'nothing is fetched until the owner asks');
-  await h.click('offer', 12);
-  assert.equal(installedReads(h), 1);
-  const html = h.rows.innerHTML;
-  for (const k of INSTALLED) {
-    assert.ok(html.includes(`value="${k.name}"`), `${k.name} is a choice`);
-    assert.ok(html.includes(k.does), `${k.name} shows what it does`);
-    assert.ok(html.includes(k.cost), `${k.name} shows what it costs`);
+await test('the component names the hosts it reads (sanity: the scan below has something to check)', () => {
+  for (const id of ['specialities-scroll', 'specialities-rows', 'speciality-suggestions', 'specialities-status', 'speciality-create', 'speciality-create-offer', 'speciality-create-skills']) {
+    assert.ok(HOSTS.includes(id), `speciality-tools.js reads #${id}`);
   }
-  assert.deepEqual(checkedIn(html), ['recall'], 'what it offers today is ticked');
-  assert.match(html, /Offering a skill turns nothing on/);
 });
 
-await test('a skill it offers that the instance no longer has is named, not offered as a choice', async () => {
-  const h = await boot();
-  await h.click('offer', 12);
-  assert.ok(!h.rows.innerHTML.includes('value="retired-skill"'), 'not a checkbox');
-  assert.match(h.rows.innerHTML, /No longer on this project, so saving drops it from the offer: <code>retired-skill<\/code>/);
-});
+for (const page of SPECIALITY_PAGES) {
+  await test(`${page}: the page carries every host the component reads, and no second copy of the create form`, async () => {
+    const h = await boot(page);
+    for (const id of HOSTS) assert.ok(h.el(id), `${page}.html: #${id} is there once the component has run`);
+    assert.ok(h.hostIds.includes('speciality-create'), `${page}.html declares the create form's host`);
+    const html = fs.readFileSync(path.join(ROOT, 'modules/hall-ui/public', `${page}.html`), 'utf8');
+    const form = html.slice(html.indexOf('<form id="speciality-create"'), html.indexOf('</form>', html.indexOf('<form id="speciality-create"')));
+    assert.doesNotMatch(form, /<(input|select|textarea)\b/, `${page}.html: the create form is EMPTY — the component renders it, so there is one copy`);
+    assert.ok(html.includes('/builders/speciality-tools.js'), `${page}.html loads the component`);
+    assert.ok(html.includes('/builders/speciality-tools.css'), `${page}.html loads its sheet`);
+  });
 
-await test('saving sends exactly the ticked skills as one PATCH, and nothing is written before', async () => {
-  const h = await boot();
-  await h.click('offer', 12);
-  assert.equal(writes(h).length, 0);
-  await h.submitOffer(12, ['recall', 'status']);
-  const w = writes(h);
-  assert.equal(w.length, 1);
-  assert.equal(w[0].method, 'PATCH');
-  assert.equal(w[0].path, '/specialities/12');
-  assert.deepEqual(w[0].body, { skills: ['recall', 'status'] });
-  assert.ok(h.toasts.some((m) => /offers 2 skills/.test(m)));
-  assert.ok(!/class="speciality-offer"/.test(h.rows.innerHTML), 'the editor closes on save');
-});
+  await test(`${page}: the create form the component renders carries every field, and the skills picker INSIDE the form it submits with`, async () => {
+    const h = await boot(page);
+    const form = h.el('speciality-create');
+    assert.deepEqual(Object.keys(form.elements).sort(), ['contract_md', 'discipline', 'name', 'sellable', 'summary', 'visibility']);
+    assert.deepEqual(form.elements.discipline.querySelectorAll('option').map((o) => o.attrs.value), ['', 'engineer', 'ideator', 'artist', 'ui']);
+    assert.deepEqual(form.elements.visibility.querySelectorAll('option').map((o) => o.attrs.value), ['private', 'project', 'public']);
+    assert.ok(form.querySelector('details#speciality-create-offer'), 'the picker is inside the form');
+    assert.ok(form.querySelector('#speciality-create-skills'), 'with the host its choices fill');
+  });
 
-await test('offering nothing is a choice too', async () => {
-  const h = await boot();
-  await h.click('offer', 12);
-  await h.submitOffer(12, []);
-  assert.deepEqual(writes(h)[0].body, { skills: [] });
-});
+  await test(`${page}: only a speciality you own has "Train" and "Offered skills"`, async () => {
+    const h = await boot(page);
+    for (const act of ['offer', 'train']) {
+      const ids = [...h.html('specialities-rows').matchAll(new RegExp(`data-act="${act}" data-id="(\\d+)"`, 'g'))].map((m) => m[1]);
+      assert.deepEqual(ids, ['12'], act);
+    }
+  });
 
-await test('the installed list is read once per page, however often the editor opens', async () => {
-  const h = await boot();
-  await h.click('offer', 12);
-  await h.click('offer', 12); // close
-  await h.click('offer', 12); // open again
-  assert.equal(installedReads(h), 1);
-});
+  await test(`${page}: opening "Offered skills" lists every installed skill with its plain description and cost, the current offer ticked`, async () => {
+    const h = await boot(page);
+    assert.equal(installedReads(h), 0, 'nothing is fetched until the owner asks');
+    await h.click(`${ROWS} button[data-act="offer"]`);
+    assert.equal(installedReads(h), 1);
+    const html = h.html('specialities-rows');
+    for (const k of INSTALLED) {
+      assert.ok(html.includes(`value="${k.name}"`), `${k.name} is a choice`);
+      assert.ok(html.includes(k.does), `${k.name} shows what it does`);
+      assert.ok(html.includes(k.cost), `${k.name} shows what it costs`);
+    }
+    assert.deepEqual(checkedIn(html), ['recall'], 'what it offers today is ticked');
+    assert.match(html, /Offering a skill turns nothing on/);
+  });
 
-await test('the create form offers the same choices, filled on first open, and sends them with the new speciality', async () => {
-  const h = await boot();
-  const box = h.els.get('speciality-create-offer');
-  const host = h.els.get('speciality-create-skills');
-  box.open = true;
-  h.handlers.get('speciality-create-offer:toggle')();
-  await h.settle();
-  for (const k of INSTALLED) assert.ok(host.innerHTML.includes(`value="${k.name}"`) && host.innerHTML.includes(k.does));
-  assert.deepEqual(checkedIn(host.innerHTML), [], 'a new speciality starts offering nothing');
-  h.create.elements.name.value = 'New one';
-  h.create.elements.discipline.value = 'engineer';
-  h.create.querySelectorAll = (sel) => (sel === 'input[name="skill"]:checked' ? [{ value: 'status' }] : []);
-  h.handlers.get('speciality-create:submit')({ preventDefault() {} });
-  await h.settle();
-  const post = writes(h).find((r) => r.method === 'POST' && r.path === '/specialities');
-  assert.ok(post, 'created');
-  assert.deepEqual(post.body.skills, ['status']);
-});
+  await test(`${page}: a skill it offers that the instance no longer has is named, not offered as a choice`, async () => {
+    const h = await boot(page);
+    await h.click(`${ROWS} button[data-act="offer"]`);
+    assert.ok(!h.html('specialities-rows').includes('value="retired-skill"'), 'not a checkbox');
+    assert.match(h.html('specialities-rows'), /No longer on this project, so saving drops it from the offer: <code>retired-skill<\/code>/);
+  });
 
-await test('settings.html carries the create form\'s picker inside the form it submits with', () => {
-  const form = HTML.slice(HTML.indexOf('<form id="speciality-create"'), HTML.indexOf('</form>', HTML.indexOf('<form id="speciality-create"')));
-  assert.match(form, /<details id="speciality-create-offer"/);
-  assert.match(form, /id="speciality-create-skills"/);
-});
+  await test(`${page}: "Find a skill" narrows the list as you type`, async () => {
+    const h = await boot(page);
+    await h.click(`${ROWS} button[data-act="offer"]`);
+    await h.type(`${OFFER} .speciality-offer__filter`, 'version');
+    const shown = h.find(`${OFFER} .speciality-offer__list`).children.filter((li) => !li.hidden).map((li) => li.querySelector('input').attrs.value);
+    assert.deepEqual(shown, ['status'], 'matched on the plain description, not only the name');
+  });
+
+  await test(`${page}: saving sends exactly the ticked skills as one PATCH, and nothing is written before`, async () => {
+    const h = await boot(page);
+    await h.click(`${ROWS} button[data-act="offer"]`);
+    assert.equal(writes(h).length, 0);
+    h.tick(`${OFFER} input[value="status"]`);
+    const ev = await h.submit(OFFER);
+    assert.equal(ev.defaultPrevented, true, 'the page does not navigate');
+    const w = writes(h);
+    assert.equal(w.length, 1);
+    assert.equal(w[0].method, 'PATCH');
+    assert.equal(w[0].path, '/specialities/12');
+    assert.deepEqual(w[0].body, { skills: ['recall', 'status'] });
+    assert.ok(h.toasts.some((m) => /offers 2 skills/.test(m)));
+    assert.ok(!/class="speciality-offer"/.test(h.html('specialities-rows')), 'the editor closes on save');
+  });
+
+  await test(`${page}: offering nothing is a choice too`, async () => {
+    const h = await boot(page);
+    await h.click(`${ROWS} button[data-act="offer"]`);
+    h.find(`${OFFER} input[value="recall"]`).checked = false;
+    await h.submit(OFFER);
+    assert.deepEqual(writes(h)[0].body, { skills: [] });
+  });
+
+  await test(`${page}: the installed list is read once per page, however often the editor opens`, async () => {
+    const h = await boot(page);
+    await h.click(`${ROWS} button[data-act="offer"]`);
+    await h.click(`${ROWS} button[data-act="offer"]`); // close
+    await h.click(`${ROWS} button[data-act="offer"]`); // open again
+    assert.equal(installedReads(h), 1);
+  });
+
+  await test(`${page}: training adds a document to your own speciality in one POST, and the form closes`, async () => {
+    const h = await boot(page);
+    await h.click(`${ROWS} button[data-act="train"]`);
+    const form = h.find(`${ROWS} form.speciality-train`);
+    assert.ok(form, 'Train opens the form in its card');
+    assert.match(form.textContent, /indexed\s+for recall, not pasted into every session/);
+    form.elements.title.value = '  How we price a swap  ';
+    form.elements.body_md.value = 'Start from the spread.';
+    await h.submit(`${ROWS} form.speciality-train`);
+    assert.deepEqual(writes(h).map((r) => [r.method, r.path, r.body]), [['POST', '/specialities/12/documents', { title: 'How we price a swap', body_md: 'Start from the spread.' }]]);
+    assert.ok(h.toasts.includes('Added.'));
+    assert.equal(h.find(`${ROWS} form.speciality-train`), null, 'the form closes on save');
+  });
+
+  await test(`${page}: a document with no title or no body is refused inline, before any request`, async () => {
+    const h = await boot(page);
+    await h.click(`${ROWS} button[data-act="train"]`);
+    h.find(`${ROWS} form.speciality-train`).elements.title.value = 'Only a title';
+    await h.submit(`${ROWS} form.speciality-train`);
+    assert.equal(writes(h).length, 0);
+    assert.equal(h.el('specialities-status').textContent, 'A document needs both a title and some content.');
+  });
+
+  await test(`${page}: a document it already knows says so`, async () => {
+    const h = await boot(page, { answer: (m, p) => (m === 'POST' && /\/documents$/.test(p) ? { status: 200, data: { skipped: true, reason: 'already_trained' } } : null) });
+    await h.click(`${ROWS} button[data-act="train"]`);
+    const form = h.find(`${ROWS} form.speciality-train`);
+    form.elements.title.value = 'T';
+    form.elements.body_md.value = 'B';
+    await h.submit(`${ROWS} form.speciality-train`);
+    assert.ok(h.toasts.includes('It already knew that one.'));
+  });
+
+  await test(`${page}: the create form offers the same choices, filled on first open, and sends them with the new speciality`, async () => {
+    const h = await boot(page);
+    const host = h.el('speciality-create-skills');
+    await h.toggle('speciality-create-offer');
+    for (const k of INSTALLED) assert.ok(host.innerHTML.includes(`value="${k.name}"`) && host.innerHTML.includes(k.does));
+    assert.deepEqual(checkedIn(host.innerHTML), [], 'a new speciality starts offering nothing');
+    const form = h.el('speciality-create');
+    form.elements.name.value = 'New one';
+    form.elements.discipline.value = 'engineer';
+    h.tick('#speciality-create-skills input[value="status"]');
+    await h.submit('#speciality-create');
+    const post = writes(h).find((r) => r.method === 'POST' && r.path === '/specialities');
+    assert.ok(post, 'created');
+    assert.deepEqual(post.body, { name: 'New one', discipline: 'engineer', summary: '', contract_md: '', visibility: 'private', sellable: false, skills: ['status'] });
+    assert.ok(h.toasts.includes('Speciality created.'));
+  });
+
+  await test(`${page}: create refuses a nameless or roleless speciality inline, and a private one cannot be for sale`, async () => {
+    const h = await boot(page);
+    const form = h.el('speciality-create');
+    await h.submit('#speciality-create');
+    assert.equal(h.el('specialities-status').textContent, 'Give it a name.');
+    form.elements.name.value = 'X';
+    await h.submit('#speciality-create');
+    assert.match(h.el('specialities-status').textContent, /^Pick which role it sits under\.$/);
+    assert.equal(writes(h).length, 0);
+    assert.equal(form.elements.sellable.disabled, true, 'private (the default) cannot be sold');
+    form.elements.visibility.value = 'public';
+    form.elements.visibility.fire('change', {});
+    assert.equal(form.elements.sellable.disabled, false);
+  });
+}
 
 summary();