@bongos/core 1.21.26 → 1.21.28

package/tests/craft_mode.mjs

@@ -1,141 +1,296 @@
-// tests/craft_mode.mjs — the claimed craft's pack pointer is INJECTED, not
-// printed (task 1002992).
+// tests/craft_mode.mjs — the hall's craft mode picker (task 1004492, goal 1000095 WA6).
 //
-// Four altitudes: the server helper over the real registry, the /me wiring, the
-// Conductor's worktree-scoped relay, and claim.js — which now prints one role line
-// but must still land a ui claim's module-owned skills (the regression this task
-// was most likely to ship). The hook itself is run end to end, against the
-// helper's real output, in tests/conductor_main_e2e.mjs.
-//
-// Run:  node tests/craft_mode.mjs
-
-import { strict as assert } from 'node:assert';
-import { createRequire } from 'node:module';
+// On entering the hall a picker asks once per session "What are you doing
+// now?" (Building, Artistry, Ideating, Governing, or Legacy mode); the answer is
+// html[data-craft], and a switch in the top bar changes it without a reload.
+// These cases boot the REAL shell-trail.js + craft-mode.js + shell.js in a DOM
+// stub, in the order every hall page loads them, and drive them the way a
+// reader does: sign in, pick a door, reload, start a new session, press the
+// switch. The criterion's own disqualifier comes first: a hall with no mode
+// chosen must render exactly as the hall did before craft modes existed.
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
 import fs from 'node:fs';
-import os from 'node:os';
 import path from 'node:path';
+import vm from 'node:vm';
 import { fileURLToPath } from 'node:url';
-import { makeRunner } from './helpers.mjs';
 
-const require = createRequire(import.meta.url);
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
-const craft = require('../src/bongos/craft-mode.js');
-const conductor = require('../.claude/hooks/conductor.js');
-const { test, summary } = makeRunner();
+const HALL = path.join(ROOT, 'modules/hall-ui/public');
+const read = (f) => fs.readFileSync(path.join(HALL, f), 'utf8');
+const SHELL = read('shell.js');
+const TRAIL = read('shell-trail.js');
+const CRAFT = read('craft-mode.js');
 
-const REGISTRY = path.join(ROOT, 'scripts', 'gds', 'discipline-modes.json');
-const MODES = craft.readModes();
+// A tiny element: attributes, a dataset, children by markup. An element built
+// from markup answers the selectors the craft code asks with a regex over that
+// markup, so a door or a checkbox the code forgot to render cannot be found.
+function makeEl(tag, html = '') {
+  const attrs = {}, listeners = {};
+  const el = {
+    tagName: tag, id: '', className: '', dataset: {}, style: {}, textContent: '', hidden: false, title: '',
+    _html: html, children: [], parentNode: null,
+    classList: { _s: new Set(), add(c) { this._s.add(c); }, remove(c) { this._s.delete(c); }, toggle(c, on) { if (on === undefined) on = !this._s.has(c); if (on) this._s.add(c); else this._s.delete(c); return on; }, contains(c) { return this._s.has(c); } },
+    setAttribute(k, v) { attrs[k] = String(v); }, getAttribute(k) { return k in attrs ? attrs[k] : null; },
+    hasAttribute(k) { return k in attrs; }, removeAttribute(k) { delete attrs[k]; },
+    addEventListener(t, fn) { (listeners[t] ||= []).push(fn); },
+    fire(t, ev) { for (const fn of listeners[t] || []) fn(ev); },
+    appendChild(c) { c.parentNode = el; el.children.push(c); return c; },
+    removeChild(c) { el.children = el.children.filter((x) => x !== c); c.parentNode = null; },
+    insertBefore(c) { return el.appendChild(c); },
+    focus() { focused.el = el; },
+    closest() { return null; },
+    querySelector(sel) { return el.querySelectorAll(sel)[0] || null; },
+    querySelectorAll(sel) { return fromMarkup(el, sel); },
+    set innerHTML(v) { el._html = String(v); el._kids = null; }, get innerHTML() { return el._html; },
+  };
+  return el;
+}
+const focused = { el: null };
+// Buttons and inputs parsed out of an element's markup, built once so a state
+// written to one (aria-pressed, checked) is the state read back later.
+function kids(el) {
+  if (el._kids) return el._kids;
+  el._kids = [...el._html.matchAll(/<(button|input)\b([^>]*)>/g)].map((m) => {
+    const k = makeEl(m[1].toUpperCase());
+    for (const a of m[2].matchAll(/([a-z-]+)(?:="([^"]*)")?/g)) {
+      if (a[1] === 'class') k.className = a[2]; else k.setAttribute(a[1], a[2] == null ? '' : a[2]);
+    }
+    k.checked = k.hasAttribute('checked');
+    k.closest = () => k;
+    return k;
+  });
+  return el._kids;
+}
+function fromMarkup(el, sel) {
+  const all = kids(el);
+  let m;
+  if ((m = /^\[([a-z-]+)\]$/.exec(sel))) return all.filter((k) => k.hasAttribute(m[1]));
+  if ((m = /^#craft-switch \[([a-z-]+)\]$/.exec(sel))) return all.filter((k) => k.hasAttribute(m[1]));
+  if ((m = /^\.([a-z-]+)$/.exec(sel))) return all.filter((k) => k.className.split(/\s+/).includes(m[1]));
+  if (sel === 'button, input') return all;
+  return [];
+}
 
-// ---- the helper, over the ONE registry ---------------------------------------
-await test('the server reads the same registry file claim.js and fitness read', () => {
-  assert.deepEqual(MODES, JSON.parse(fs.readFileSync(REGISTRY, 'utf8')).modes);
-});
+// One page load. `session` is the tab's sessionStorage and `store` the
+// browser's localStorage: pass the same objects to a second boot and it is a
+// reload; a fresh `session` with the same `store` is a new browser session.
+function boot({ craft = true, session = {}, store = {}, throws = false, optOut = false, narrow = false } = {}) {
+  const events = [];
+  const root = makeEl('HTML');
+  const topbar = makeEl('DIV');
+  const sidebar = makeEl('NAV');
+  const body = makeEl('BODY');
+  body.dataset.page = 'work';
+  if (optOut) body.setAttribute('data-craft-mode', 'off');
+  const els = { 'app-topbar': topbar, 'app-sidebar': sidebar };
+  const docListeners = {};
+  const documentObj = {
+    body, referrer: '', documentElement: root, activeElement: null,
+    getElementById(id) {
+      if (els[id]) return els[id];
+      if (id === 'craft-switch') {
+        if (!topbar._html.includes('id="craft-switch"')) return null;
+        const sw = els[id] = makeEl('DIV', topbar._html.match(/<div class="craft-switch[\s\S]*?<\/div>/)[0]);
+        return sw;
+      }
+      if (/^(fullscreen-toggle|theme-toggle|zoom-toggle|topbar-menu|topbar-title|topbar-jump|topbar-back|founding-band|fullscreen-hint|skip-link|app-foot|app-scrim|shell-signin|shell-user|logout-link|craft-picker)$/.test(id)) {
+        if (id === 'craft-picker') return body.children.find((c) => c.id === 'craft-picker') || null;
+        return topbar._html.includes(`id="${id}"`) ? (els[id] = els[id] || makeEl('X')) : null;
+      }
+      return null;
+    },
+    querySelector: () => null,
+    querySelectorAll: (sel) => (sel.startsWith('#craft-switch') && els['craft-switch'] ? els['craft-switch'].querySelectorAll(sel) : []),
+    createElement: (t) => makeEl(t.toUpperCase()),
+    addEventListener(t, fn) { (docListeners[t] ||= []).push(fn); },
+    removeEventListener(t, fn) { docListeners[t] = (docListeners[t] || []).filter((f) => f !== fn); },
+    dispatchEvent(ev) { events.push(ev); return true; },
+    get cookie() { return ''; }, set cookie(_v) {},
+  };
+  const location = { hostname: 'h', origin: 'https://h', href: 'https://h/work', pathname: '/work', hash: '', search: '', reloads: 0, assign() { this.reloads++; }, replace() { this.reloads++; }, reload() { this.reloads++; } };
+  const mk = (obj) => ({
+    getItem: (k) => { if (throws) throw new Error('SecurityError'); return k in obj ? obj[k] : null; },
+    setItem: (k, v) => { if (throws) throw new Error('SecurityError'); obj[k] = String(v); },
+    removeItem: (k) => { if (throws) throw new Error('SecurityError'); delete obj[k]; },
+  });
+  const windowObj = {
+    __BRANDING__: {}, __MODULES__: { enabled: {} },
+    BongosClient: { createClient: () => ({ request: () => new Promise(() => {}) }) },
+    matchMedia: (q) => ({ matches: narrow && /max-width: 640px/.test(q), addEventListener() {} }),
+    localStorage: mk(store), sessionStorage: mk(session), location,
+    clearTimeout() {}, setTimeout() { return 0; }, requestAnimationFrame() {}, scrollTo() {},
+    addEventListener() {}, dispatchEvent() { return true; },
+  };
+  const sandbox = {
+    window: windowObj, document: documentObj, location, console, URL, URLSearchParams, queueMicrotask,
+    setTimeout() { return 0; }, clearTimeout() {},
+    Event: class { constructor(t) { this.type = t; } },
+    CustomEvent: class { constructor(t, i) { this.type = t; Object.assign(this, i); } },
+  };
+  sandbox.globalThis = sandbox;
+  vm.createContext(sandbox);
+  vm.runInContext(TRAIL, sandbox, { filename: 'shell-trail.js' });
+  if (craft) vm.runInContext(CRAFT, sandbox, { filename: 'craft-mode.js' });
+  vm.runInContext(SHELL, sandbox, { filename: 'shell.js' });
+  const shell = windowObj.OTBShell;
+  const picker = () => body.children.find((c) => c.id === 'craft-picker') || null;
+  const sw = () => documentObj.getElementById('craft-switch');
+  return {
+    root, topbar, sidebar, body, session, store, location, events,
+    mode: () => root.dataset.craft,
+    picker,
+    signIn: (builder = { id: 7, rank: 'thetes' }) => shell.applyAccess({ authed: true, rank: builder.rank, builder }),
+    signOut: () => shell.applyAccess({ authed: false }),
+    // Press a picker button: a door, Legacy, or the close button.
+    pick(attr, value, { askAgain = true } = {}) {
+      const p = picker();
+      const box = p.querySelector('[data-craft-again]');
+      if (box) box.checked = askAgain;
+      const btn = p.querySelectorAll(`[${attr}]`).find((b) => value == null || b.getAttribute(attr) === value);
+      assert.ok(btn, `the picker renders a [${attr}${value ? '=' + value : ''}] button`);
+      p.fire('click', { target: btn });
+    },
+    press(mode) {
+      const btn = sw().querySelectorAll('[data-craft-opt]').find((b) => b.getAttribute('data-craft-opt') === mode);
+      assert.ok(btn, `the switch renders a ${mode} option`);
+      sw().fire('click', { target: btn });
+    },
+    pressed: () => sw().querySelectorAll('[data-craft-opt]').filter((b) => b.getAttribute('aria-pressed') === 'true').map((b) => b.getAttribute('data-craft-opt')),
+    escape() { for (const fn of docListeners.keydown || []) fn({ key: 'Escape', preventDefault() {} }); },
+  };
+}
 
-await test('every registry craft yields a contract naming its pack or skill, with its directive', () => {
-  const names = Object.keys(MODES);
-  assert.ok(names.length >= 3, 'the registry was read at all');
-  for (const d of names) {
-    const m = craft.describeCraftMode(d, MODES);
-    assert.ok(m && m.inject, `${d} injects`);
-    assert.equal(m.discipline, d);
-    const pointer = MODES[d].pack || `/${MODES[d].skill}`;
-    assert.ok(m.contract.includes(pointer), `${d} names ${pointer}`);
-    assert.ok(m.contract.includes(MODES[d].directive.slice(0, 40)), `${d} carries its directive`);
-  }
-  assert.match(craft.describeCraftMode('engineer', MODES).contract, /read docs\/packs\/engineer\.md/);
-  assert.match(craft.describeCraftMode('ui', MODES).contract, /— \/design/, 'a skill is a command to invoke, not a file to read');
-});
+const MODES = ['building', 'artistry', 'ideating', 'governing', 'legacy'];
+const noSwitch = (html) => html.replace(/<div class="craft-switch[\s\S]*?<\/div>/, '');
 
-await test('fail-open: no craft, an unknown craft, or an unreadable registry yields nothing', () => {
-  assert.equal(craft.describeCraftMode(null, MODES), null);
-  assert.equal(craft.describeCraftMode('governor', MODES), null);
-  assert.equal(craft.describeCraftMode('engineer', null), null);
-  assert.deepEqual(craft.readModes(path.join(os.tmpdir(), 'no-such-registry.json')), {});
-  const bad = path.join(fs.mkdtempSync(path.join(os.tmpdir(), 'craft-')), 'modes.json');
-  fs.writeFileSync(bad, '{ not json');
-  assert.deepEqual(craft.readModes(bad), {});
+test('NO MODE IS THE HALL AS TODAY: with no mode chosen, nothing but the switch differs from a hall without craft modes', () => {
+  const before = boot({ craft: false });
+  const after = boot({ craft: true });
+  assert.equal(after.mode(), undefined, 'no html[data-craft]');
+  assert.deepEqual({ ...after.root.dataset }, { ...before.root.dataset }, 'the root carries exactly the attributes it did');
+  assert.equal(after.sidebar.innerHTML, before.sidebar.innerHTML, 'the sidebar is byte-identical');
+  assert.equal(noSwitch(after.topbar.innerHTML), before.topbar.innerHTML, 'the top bar differs by the switch alone');
+  assert.ok(after.topbar.innerHTML.includes('id="craft-switch"'), 'and the switch is there to choose one');
+  assert.equal(after.picker(), null, 'nobody is asked before a signed-in builder is known');
 });
 
-await test('the default registry is read once per process; an explicit file is read fresh', () => {
-  assert.equal(craft.readModes(), craft.readModes(), 'GET /me does not re-read and re-parse per request');
-  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'craft-'));
-  const f = path.join(dir, 'modes.json');
-  fs.writeFileSync(f, JSON.stringify({ modes: { a: { directive: 'x' } } }));
-  assert.deepEqual(Object.keys(craft.readModes(f)), ['a']);
-  fs.writeFileSync(f, JSON.stringify({ modes: { b: { directive: 'y' } } }));
-  assert.deepEqual(Object.keys(craft.readModes(f)), ['b'], 'claim.js always sees the file as it is now');
+test('a signed-in builder is asked ONCE per session, and a reload does not ask again', () => {
+  const session = {};
+  const p = boot({ session });
+  p.signIn();
+  assert.ok(p.picker(), 'the picker opens');
+  const html = p.picker().innerHTML;
+  assert.match(html, /role="dialog" aria-modal="true"/);
+  assert.match(html, /What are you doing now\?/);
+  for (const m of ['building', 'artistry', 'ideating', 'governing']) assert.match(html, new RegExp(`data-craft-pick="${m}"`), `a ${m} door`);
+  assert.match(html, /data-craft-pick="legacy"[^>]*>Legacy mode/, 'Legacy mode is the fifth choice (owner, 2026-10-01)');
+  p.escape();
+  assert.equal(p.picker(), null, 'Escape closes it without choosing');
+  assert.equal(p.mode(), undefined, 'and leaves the hall with no mode');
+  const reload = boot({ session });
+  reload.signIn();
+  assert.equal(reload.picker(), null, 'the same session is not asked twice');
 });
 
-// ---- /me carries it on each claim ---------------------------------------------
-await test('GET /me puts each claim\'s craft_mode on the claim, from the helper', () => {
-  const me = fs.readFileSync(path.join(ROOT, 'src/bongos/routes/me.js'), 'utf8');
-  assert.match(me, /require\('\.\.\/craft-mode'\)/);
-  assert.match(me, /craft_mode: describeCraftMode\(c\.discipline, craftModes\)/);
-  assert.doesNotMatch(me, /"modes"\s*:/, 'no second copy of the registry in the route');
+test('a visitor who is not signed in is never asked', () => {
+  const p = boot();
+  p.signOut();
+  assert.equal(p.picker(), null);
 });
 
-// ---- the Conductor relays THIS worktree's craft only ---------------------------
-const claim = (id, discipline) => ({ task_id: String(id), title: 't', touches: [], worktree_name: `task-${id}`, discipline, craft_mode: craft.describeCraftMode(discipline, MODES) });
-const craftIds = (out) => out.filter((a) => String(a.id).startsWith('craft:')).map((a) => a.id);
+test('choosing a door sets html[data-craft] for every page of the session, and says so on document', () => {
+  const session = {}, store = {};
+  const p = boot({ session, store });
+  p.signIn();
+  p.pick('data-craft-pick', 'ideating');
+  assert.equal(p.picker(), null, 'the picker closes');
+  assert.equal(p.mode(), 'ideating');
+  assert.ok(p.events.some((e) => e.type === 'otb:craft' && e.detail.mode === 'ideating'), 'otb:craft fires with the mode');
+  assert.deepEqual(p.pressed(), ['ideating'], 'the switch lights the chosen mode');
+  const next = boot({ session, store });
+  assert.equal(next.mode(), 'ideating', 'the next page of the session reads it before /me answers');
+  assert.equal(store['hall-craft-keep'], undefined, '"Ask me again next session" was ticked, so nothing outlives the session');
+  const tomorrow = boot({ store });
+  tomorrow.signIn();
+  assert.equal(tomorrow.mode(), undefined, 'a new session starts with no mode');
+  assert.ok(tomorrow.picker(), 'and asks again');
+});
 
-await test('the claim bound to this worktree gets its craft; the other tree\'s does not', () => {
-  const claims = [claim(1, 'engineer'), claim(2, 'ideator')];
-  assert.deepEqual(craftIds(conductor.evaluateTriggers({ activeClaims: claims, worktree: 'task-1' })), ['craft:engineer']);
-  assert.deepEqual(craftIds(conductor.evaluateTriggers({ activeClaims: claims, worktree: 'task-2' })), ['craft:ideator']);
+test('unticking "Ask me again next session" keeps the mode for later sessions', () => {
+  const store = {};
+  const p = boot({ store });
+  p.signIn();
+  p.pick('data-craft-pick', 'governing', { askAgain: false });
+  assert.equal(store['hall-craft-keep'], 'governing');
+  const tomorrow = boot({ store });
+  tomorrow.signIn();
+  assert.equal(tomorrow.mode(), 'governing', 'the kept mode applies');
+  assert.equal(tomorrow.picker(), null, 'and nobody is asked');
 });
 
-await test('no bound claim, no session, or no registry entry: nothing is injected', () => {
-  const claims = [claim(1, 'engineer')];
-  assert.deepEqual(craftIds(conductor.evaluateTriggers({ activeClaims: claims, worktree: 'task-9' })), [], 'an unrelated tree');
-  assert.deepEqual(craftIds(conductor.evaluateTriggers({ activeClaims: claims, worktree: null })), [], 'not in a worktree');
-  assert.deepEqual(craftIds(conductor.evaluateTriggers({ activeClaims: null, worktree: 'task-1' })), [], 'no session / no network');
-  assert.deepEqual(craftIds(conductor.evaluateTriggers({ activeClaims: [{ ...claim(1, 'governor') }], worktree: 'task-1' })), [], 'a craft with no entry');
-  assert.deepEqual(craftIds(conductor.evaluateTriggers({ activeClaims: [{ ...claim(1, 'engineer'), craft_mode: { inject: true, contract: '' } }], worktree: 'task-1' })), [], 'an empty contract');
+test('THE HEADER SWITCH changes the mode without a reload, and offers all five', () => {
+  const p = boot();
+  const opts = [...p.topbar.innerHTML.matchAll(/data-craft-opt="([a-z]+)"/g)].map((m) => m[1]);
+  assert.deepEqual(opts, MODES, 'the four crafts, then Legacy');
+  p.press('artistry');
+  assert.equal(p.mode(), 'artistry');
+  p.press('legacy');
+  assert.equal(p.mode(), 'legacy', 'anyone can go back to the old view at any time');
+  assert.deepEqual(p.pressed(), ['legacy']);
+  assert.equal(p.location.reloads, 0, 'no navigation happened');
+  assert.equal(p.session['hall-craft'], 'legacy', 'and the session remembers it');
 });
 
-// ---- claim.js: one role line, and the ui skills still land ---------------------
-const claimCli = require('../scripts/gds/claim.js');
-const materialize = require('../scripts/gds/claude-materialize.js');
+test('on a phone the switch shows only the current mode, and tapping it opens the picker', () => {
+  const session = { 'hall-craft': 'building' };
+  const p = boot({ session, narrow: true });
+  p.press('building');
+  assert.ok(p.picker(), 'the current mode opens the picker');
+  assert.equal(p.mode(), 'building', 'without changing the mode');
+});
 
-function capture(fn) {
-  const lines = [];
-  const orig = console.log;
-  console.log = (...a) => { lines.push(a.join(' ')); };
-  try { fn(); } finally { console.log = orig; }
-  return lines.filter((l) => l !== '');
-}
+test('artists start on Artistry: the door is pre-selected and the picker says why', () => {
+  const p = boot();
+  p.signIn({ id: 3, rank: 'thetes', main_discipline: 'artist', preferred_disciplines: ['engineer', 'artist'] });
+  const html = p.picker().innerHTML;
+  assert.match(html, /craft-door--artistry craft-door--pre"/);
+  assert.match(html, /Artists start on Artistry\./);
+  const eng = boot();
+  eng.signIn({ id: 4, rank: 'thetes', main_discipline: 'engineer', preferred_disciplines: ['artist'] });
+  assert.doesNotMatch(eng.picker().innerHTML, /craft-door--pre/, 'a main role that is not artist pre-selects nothing');
+  const unset = boot();
+  unset.signIn({ id: 5, rank: 'thetes', main_discipline: null, preferred_disciplines: ['artist'] });
+  assert.match(unset.picker().innerHTML, /craft-door--artistry craft-door--pre"/, 'with no main role, the first craft decides');
+});
 
-await test('claim.js prints exactly one role line and no directive block', () => {
-  const lines = capture(() => claimCli.printRoleLine({ discipline: 'engineer' }));
-  assert.deepEqual(lines, ['▶ Engineering session — read docs/packs/engineer.md']);
-  const src = fs.readFileSync(path.join(ROOT, 'scripts/gds/claim.js'), 'utf8');
-  assert.doesNotMatch(src, /mode\.directive\}/, 'the directive is no longer printed');
-  assert.doesNotMatch(src, /Your pack:/);
+test('storage that throws is never asked and never wears a mode', () => {
+  const p = boot({ throws: true });
+  p.signIn();
+  assert.equal(p.picker(), null, 'it could not remember being asked, so it would ask on every page');
+  assert.equal(p.mode(), undefined);
 });
 
-await test('claiming a ui task STILL materialises its module-owned skills', () => {
-  const saved = { into: materialize.materializeModuleSkillsIntoCore, root: materialize.isCoreCheckoutRoot };
-  const calls = [];
-  materialize.isCoreCheckoutRoot = () => true;
-  materialize.materializeModuleSkillsIntoCore = (opts) => { calls.push(opts); return { materialized: ['impeccable', 'minimalist-ui'] }; };
-  try {
-    const lines = capture(() => claimCli.printRoleLine({ discipline: 'ui' }));
-    assert.equal(calls.length, 1, 'the ui claim landed its skills');
-    assert.equal(lines[0], '▶ UI design session — /design');
-    assert.match(lines[1], /2 module-owned skill\(s\)/);
-    calls.length = 0;
-    capture(() => claimCli.printRoleLine({ discipline: 'engineer' }));
-    assert.equal(calls.length, 0, 'a craft that did not opt in lands nothing');
-  } finally {
-    materialize.materializeModuleSkillsIntoCore = saved.into;
-    materialize.isCoreCheckoutRoot = saved.root;
-  }
+test('a page can opt out with <body data-craft-mode="off">', () => {
+  const p = boot({ optOut: true, session: { 'hall-craft': 'artistry' } });
+  p.signIn();
+  assert.doesNotMatch(p.topbar.innerHTML, /craft-switch/, 'no switch');
+  assert.equal(p.picker(), null, 'no picker');
+  assert.equal(p.mode(), undefined, 'no mode');
 });
 
-await test('claim.js fails open: no craft or an unknown craft prints nothing and never throws', () => {
-  assert.deepEqual(capture(() => claimCli.printRoleLine({})), []);
-  assert.deepEqual(capture(() => claimCli.printRoleLine({ discipline: 'governor' })), []);
-  assert.deepEqual(capture(() => claimCli.printRoleLine(null)), []);
+test('a stored value that is not a mode is ignored, not trusted', () => {
+  const p = boot({ session: { 'hall-craft': '"><img src=x>' }, store: { 'hall-craft-keep': 'admin' } });
+  assert.equal(p.mode(), undefined);
 });
 
-summary();
+test('every hall page loads shell-trail.js and craft-mode.js right before shell.js, deferred alike', () => {
+  const pages = fs.readdirSync(HALL).filter((f) => f.endsWith('.html') && read(f).includes('/builders/shell.js'));
+  assert.ok(pages.length >= 30, `found ${pages.length} hall pages`);
+  for (const f of pages) {
+    const tags = [...read(f).matchAll(/<script src="\/builders\/([a-z-]+)\.js[^"]*"( defer)?><\/script>/g)].map((m) => [m[1], !!m[2]]);
+    const at = tags.findIndex((t) => t[0] === 'shell');
+    assert.deepEqual(tags.slice(at - 2, at + 1).map((t) => t[0]), ['shell-trail', 'craft-mode', 'shell'], f);
+    assert.equal(new Set(tags.slice(at - 2, at + 1).map((t) => t[1])).size, 1, `${f}: all three load the same way`);
+  }
+});

package/tests/goal_map_page.mjs

@@ -431,9 +431,9 @@ await test('the page is the sky\'s own surface — the same sheet and the same s
   assert.match(html, /<main id="hall-main" class="sky-stage">/, 'the sky is drawn in the stage, the skip link\'s target');
   const scripts = (h) => [...h.matchAll(/<script src="\/builders\/([^"?]+)\?v=([^"]+)"/g)].map((m) => [m[1], m[2]]);
   // criterion-uat-ui.js (task 1004402): the rings' UAT state words, shared with the goal page.
-  assert.deepEqual(scripts(html).filter((s) => s[0] !== 'shell.js').map((s) => s[0]), ['idea-objects.js', 'criterion-uat-ui.js', 'sky-data.js', 'sky-layout.js', 'sky-draw.js', 'sky-interaction.js', 'sky-panel.js', 'sky-composer.js', 'sky-tour.js']);
+  assert.deepEqual(scripts(html).filter((s) => !['shell-trail.js', 'craft-mode.js', 'shell.js'].includes(s[0])).map((s) => s[0]), ['idea-objects.js', 'criterion-uat-ui.js', 'sky-data.js', 'sky-layout.js', 'sky-draw.js', 'sky-interaction.js', 'sky-panel.js', 'sky-composer.js', 'sky-tour.js']);
   // Both doors load the shell (tasks 1004327, 1004430); the SKY's files are the same.
-  const skyScripts = (h) => scripts(h).filter((s) => s[0] !== 'shell.js');
+  const skyScripts = (h) => scripts(h).filter((s) => !['shell-trail.js', 'craft-mode.js', 'shell.js'].includes(s[0]));
   assert.deepEqual(skyScripts(html), skyScripts(thinking), 'the two doors load the same sky files at the same stamp');
   assert.equal(html.match(/thinking\.css\?v=([^"]+)/)[1], thinking.match(/thinking\.css\?v=([^"]+)/)[1]);
   assert.match(read('thinking.css'), /body\[data-page\] \.sky-stage \{/, 'the sheet dresses the one stage both doors draw in inside the hall');

package/tests/hall_city.mjs

@@ -253,7 +253,7 @@ test('the city sits in the hall chrome, behind the shell\'s full-screen switch',
   for (const id of ['app-sidebar', 'app-scrim', 'app-topbar']) assert.match(html, new RegExp(`id="${id}"`), id);
   assert.match(html, /<main id="hall-main" class="city-main">\s*<div class="city-top">/, 'the stage is the one <main>, the strip inside it');
   const scripts = [...html.matchAll(/<script src="\/builders\/([a-z-]+)\.js/g)].map((m) => m[1]);
-  assert.deepEqual(scripts, ['shell', 'palette', 'city-draw', 'city'], 'the shell first, as on every hall page');
+  assert.deepEqual(scripts, ['shell-trail', 'craft-mode', 'shell', 'palette', 'city-draw', 'city'], 'the shell first, as on every hall page');
   const css = read('city.css').replace(/\/\*[\s\S]*?\*\//g, '');
   assert.match(css, /\.city-main \{ position: fixed; top: var\(--topbar-h, 56px\); left: var\(--sidebar-w-rail, 64px\);[^}]*contain: layout paint;/);
   assert.match(css, /html\[data-fullscreen="on"\] \.city-main \{ top: 0; left: 0; \}/);

package/tests/hall_fullscreen.mjs

@@ -22,6 +22,8 @@ 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 SHELL = fs.readFileSync(path.join(HALL, 'shell.js'), 'utf8');
+// task 1004492: the way back lives in shell-trail.js, which every page loads first.
+const TRAIL = fs.readFileSync(path.join(HALL, 'shell-trail.js'), 'utf8');
 const read = (f) => fs.readFileSync(path.join(HALL, f), 'utf8');
 
 // Boot the shell once — one page load. `store` is the browser's localStorage and
@@ -33,7 +35,8 @@ const read = (f) => fs.readFileSync(path.join(HALL, f), 'utf8');
 // <body data-back-fallback> and `exits` how many [data-shell-exit] links the
 // page placed for the shell to fill (task 1004477).
 function boot({ page = 'thinking', optIn = true, store = {}, storageThrows = false,
-  referrer = '', search = '', session = {}, fallback = null, exits = 0, path = null, meId = null } = {}) {
+  referrer = '', search = '', session = {}, fallback = null, exits = 0, path = null, meId = null,
+  hash = '', sessionThrows = false } = {}) {
   const els = new Map();
   const windowListeners = {};
   const timers = [];
@@ -87,11 +90,13 @@ function boot({ page = 'thinking', optIn = true, store = {}, storageThrows = fal
     addEventListener() {}, dispatchEvent() {},
     get cookie() { return ''; }, set cookie(_v) {},
   };
-  const location = { hostname: 'h', origin: 'https://h', href: 'https://h/' + page + search, pathname: path || '/' + page, hash: '', search, assign() {}, replace() {} };
+  const location = { hostname: 'h', origin: 'https://h', href: 'https://h/' + page + search, pathname: path || '/' + page, hash, search, assign() {}, replace() {} };
+  // `session` is the TAB's sessionStorage: pass one object to several boots and
+  // they are page loads in one tab (the trail, task 1004476).
   const sessionStorage = {
-    getItem: (k) => (k in session ? session[k] : null),
-    setItem: (k, v) => { session[k] = String(v); },
-    removeItem: (k) => { delete session[k]; },
+    getItem: (k) => { if (sessionThrows) throw new Error('SecurityError'); return k in session ? session[k] : null; },
+    setItem: (k, v) => { if (sessionThrows) throw new Error('SecurityError'); session[k] = String(v); },
+    removeItem: (k) => { if (sessionThrows) throw new Error('SecurityError'); delete session[k]; },
   };
   const localStorage = {
     getItem: (k) => { if (storageThrows) throw new Error('SecurityError'); return k in store ? store[k] : null; },
@@ -118,6 +123,7 @@ function boot({ page = 'thinking', optIn = true, store = {}, storageThrows = fal
   };
   sandbox.globalThis = sandbox;
   vm.createContext(sandbox);
+  vm.runInContext(TRAIL, sandbox, { filename: 'shell-trail.js' });
   vm.runInContext(SHELL, sandbox, { filename: 'shell.js' });
   const root = documentObj.documentElement;
   return {
@@ -131,6 +137,11 @@ function boot({ page = 'thinking', optIn = true, store = {}, storageThrows = fal
     shell: () => windowObj.OTBShell,
     session,
     resizes: () => resizes,
+    // A hash route moving without a page load (a goal opened on /goals).
+    go(h) { location.hash = h; for (const fn of windowListeners.hashchange || []) fn({ type: 'hashchange' }); },
+    trail: () => JSON.parse(session['hall-nav-trail'] || '[]').map((c) => c.label),
+    crumbs: () => [...topbar._html.matchAll(/class="topbar-crumb" href="([^"]*)">([^<]*)</g)].map((m) => `${m[2]} ${m[1]}`),
+    back: () => { const m = /id="topbar-back" href="([^"]*)"[^>]*>(?:<svg[\s\S]*?<\/svg>)?<span class="topbar-back__label">([^<]*)</.exec(topbar._html); return m ? `${m[2]} ${m[1]}` : null; },
     // Press a key the way the browser dispatches it: every window listener,
     // then the page may mark the press used, then the queued timers run.
     press(key, { target = { tagName: 'CANVAS' }, pageUses = false } = {}) {
@@ -277,6 +288,115 @@ test('Back: an origin\'s own ?from= is dropped, so one page\'s way back never ch
   assert.match(p.topbar(), /href="\/roster\?q=a"/);
 });
 
+// THE TRAIL (task 1004476). The owner's case: Goals -> goal 12 -> task 340 ->
+// an idea shows "Goals › goal 12 › task 340", each a link, and Back is the last.
+// One `session` object across boots is one browser tab.
+function walkToIdea() {
+  const tab = {};
+  const goals = boot({ page: 'goals', optIn: false, path: '/goals', session: Object.assign(tab, { 'hall-nav-hop': '/goals' }) });
+  goals.go('#/goal/12');
+  boot({ page: 'task', optIn: false, path: '/task/340', search: '?from=' + encodeURIComponent('/goals#/goal/12'), fallback: '/work', session: tab });
+  const idea = boot({ page: 'idea', optIn: false, path: '/idea/4', referrer: 'https://h/task/340', fallback: '/thinking', session: tab });
+  return { tab, idea };
+}
+
+test('trail: a drill-down two layers deep shows every step, each a link, and Back is the last', () => {
+  const { tab, idea } = walkToIdea();
+  assert.deepEqual(idea.crumbs(), ['Goals /goals', 'goal 12 /goals#/goal/12']);
+  assert.equal(idea.back(), 'task 340 /task/340', 'the step before this page is still the Back link');
+  assert.match(idea.topbar(), /<nav class="topbar-trail topbar-trail--long" aria-label="Breadcrumb">/);
+  assert.deepEqual(JSON.parse(tab['hall-nav-trail']).map((c) => c.label), ['Goals', 'goal 12', 'task 340', 'idea 4']);
+});
+
+test('trail: one step back is exactly the Back link it always was', () => {
+  const tab = {};
+  boot({ page: 'roster', optIn: false, path: '/roster', session: Object.assign(tab, { 'hall-nav-hop': '/roster' }) });
+  const p = boot({ page: 'profile', optIn: false, search: '?id=7', referrer: 'https://h/roster', session: tab });
+  assert.doesNotMatch(p.topbar(), /topbar-trail|topbar-crumb/);
+  assert.match(p.topbar(), /<a class="topbar-back" id="topbar-back" href="\/roster" title="Back to Builders"><svg/);
+});
+
+test('trail: returning to a crumb trims everything after it, and a reload keeps it', () => {
+  const { tab } = walkToIdea();
+  const goal = boot({ page: 'goals', optIn: false, path: '/goals', hash: '#/goal/12', referrer: 'https://h/idea/4', session: tab });
+  assert.deepEqual(goal.crumbs(), [], 'one step left, so just Back');
+  assert.equal(goal.back(), 'Goals /goals');
+  assert.deepEqual(goal.trail(), ['Goals', 'goal 12']);
+  // A reload keeps its referrer: the task opened from the goal again.
+  const task = boot({ page: 'task', optIn: false, path: '/task/340', referrer: 'https://h/goals', fallback: '/work', session: tab });
+  const again = boot({ page: 'task', optIn: false, path: '/task/340', referrer: 'https://h/goals', fallback: '/work', session: tab });
+  for (const p of [task, again]) {
+    assert.deepEqual(p.crumbs(), ['Goals /goals'], 'a referrer has no #hash, and still finds goal 12');
+    assert.equal(p.back(), 'goal 12 /goals#/goal/12');
+  }
+  assert.deepEqual(again.trail(), ['Goals', 'goal 12', 'task 340']);
+});
+
+test('trail: a hash route back to a crumb trims, and a view switch only renames the page', () => {
+  const tab = {};
+  const goals = boot({ page: 'goals', optIn: false, path: '/goals', session: Object.assign(tab, { 'hall-nav-hop': '/goals' }) });
+  goals.go('#/goal/12');
+  assert.deepEqual(goals.trail(), ['Goals', 'goal 12']);
+  goals.go('');
+  assert.deepEqual(goals.trail(), ['Goals'], 'back to the list is a return, not a step');
+  goals.go('#archived');
+  assert.deepEqual(goals.trail(), ['Goals'], 'a view of the same page is not a drill-down');
+});
+
+test('trail: a sidebar hop starts over', () => {
+  const { tab } = walkToIdea();
+  const work = boot({ page: 'work', optIn: false, path: '/work', referrer: 'https://h/idea/4', session: Object.assign(tab, { 'hall-nav-hop': '/work' }) });
+  assert.doesNotMatch(work.topbar(), /topbar-back/);
+  assert.deepEqual(work.trail(), ['Tasks']);
+  const task = boot({ page: 'task', optIn: false, path: '/task/9', referrer: 'https://h/work', fallback: '/work', session: tab });
+  assert.deepEqual(task.crumbs(), []);
+  assert.equal(task.back(), 'Tasks /work');
+});
+
+test('trail: an origin the trail does not know starts a fresh one by the ?from= rules', () => {
+  const { tab } = walkToIdea();
+  const p = boot({ page: 'profile', optIn: false, search: '?id=7&from=%2Froster', referrer: 'https://h/idea/4', session: tab });
+  assert.deepEqual(p.crumbs(), [], 'the old trail is not this page\'s way here');
+  assert.equal(p.back(), 'Builders /roster');
+  assert.deepEqual(p.trail(), ['Builders', 'Profile']);
+});
+
+test('trail: capped at four crumbs, and on a phone the middle collapses', () => {
+  const tab = {};
+  boot({ page: 'goals', optIn: false, path: '/goals', session: Object.assign(tab, { 'hall-nav-hop': '/goals' }) });
+  let prev = '/goals';
+  let last;
+  for (const id of [1, 2, 3, 4, 5]) {
+    last = boot({ page: 'task', optIn: false, path: `/task/${id}`, referrer: `https://h${prev}`, fallback: '/work', session: tab });
+    prev = `/task/${id}`;
+  }
+  assert.deepEqual(last.crumbs(), ['task 1 /task/1', 'task 2 /task/2', 'task 3 /task/3'], 'Goals fell off the front');
+  assert.equal(last.back(), 'task 4 /task/4');
+  assert.equal(last.trail().length, 5, 'four crumbs plus this page');
+  const html = last.topbar();
+  assert.equal((html.match(/topbar-trail__step--mid/g) || []).length, 2, 'every crumb between the first and Back is the middle');
+  assert.match(html, /<nav class="topbar-trail topbar-trail--long"/);
+  assert.match(html, /<span class="topbar-trail__more"><a class="topbar-crumb topbar-crumb--more" href="\/task\/1" title="task 1 › task 2 › task 3" aria-label="task 1">…<\/a>/,
+    'the fold is a link to the start of the trail, naming what it hides');
+  const css = read('style.css');
+  assert.match(css, /@media \(max-width: 640px\) \{\s*\.topbar-trail__step--mid \{ display: none; \}\s*\.topbar-trail--long \.topbar-trail__more \{ display: inline-flex; \}/,
+    'source: on a phone the middle hides and "…" stands in');
+  assert.match(css, /@media \(max-width: 480px\) \{\s*\.topbar-trail__step--first \{ display: none; \}/, 'source: narrower, the first crumb folds too');
+  assert.match(css, /@media \(max-width: 360px\) \{\s*\.topbar-trail__mark, \.topbar-trail \.topbar-trail__more, \.topbar-trail \.topbar-back__label \{ display: none; \}/,
+    'source: narrowest, only the Back arrow is left');
+});
+
+test('trail: a hostile stored crumb is dropped, and storage that throws keeps the one-step Back', () => {
+  const tab = { 'hall-nav-trail': JSON.stringify([{ href: '//evil.example', label: 'x' }, { href: '/api/gds/x', label: 'y' },
+    { href: 'javascript:alert(1)', label: 'z' }, { href: '/goals', label: '<b>Goals</b>' }]) };
+  const p = boot({ page: 'task', optIn: false, path: '/task/9', referrer: 'https://h/goals', fallback: '/work', session: tab });
+  assert.equal(p.back(), '&lt;b&gt;Goals&lt;/b&gt; /goals', 'a stored label is escaped');
+  assert.deepEqual(JSON.parse(tab['hall-nav-trail']).map((c) => c.href), ['/goals', '/task/9']);
+  const locked = boot({ page: 'task', optIn: false, path: '/task/9', referrer: 'https://h/goals', fallback: '/work', sessionThrows: true });
+  assert.equal(locked.back(), 'Goals /goals');
+  assert.deepEqual(locked.crumbs(), []);
+});
+
 test('an opted-in page renders ONE switch in the top bar, off by default', () => {
   const p = boot();
   const btn = p.button();