@bongos/core 1.21.182 → 1.22.2

package/scripts/bongos/review-sheet.js

@@ -24,9 +24,7 @@ const path = require('node:path');
 const { pathToFileURL } = require('node:url');
 const { spawn } = require('node:child_process');
 
-function escapeHtml(s) {
-  return String(s == null ? '' : s).replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]));
-}
+const { escapeHtml } = require('../../src/html-escape'); // the one server escaper (task 1004876)
 
 // parseArgs — the flags above; `shots` keep their order. A --shot with no "="
 // is an error, not a guess: the caption and the path cannot be told apart.

package/scripts/bongos/start.js

@@ -268,7 +268,7 @@ function claimableTable(rows, rewardFromServer, goals) {
 // the same card every time, app-native. Falls back to the markdown card when
 // the client can't draw widgets. Design system: flat, 0.5px borders, CSS
 // theme vars (light/dark), Tabler icons, no emoji.
-const hesc = (s) => String(s == null ? '' : s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+const { escapeHtml: hesc } = require('../../src/html-escape'); // the one server escaper (task 1004876); it also escapes '
 const jsq = (s) => String(s == null ? '' : s).replace(/\\/g, '\\\\').replace(/'/g, "\\'").replace(/\n/g, ' ');
 
 function miniBar(pct) {

package/scripts/bongos/status.js

@@ -223,7 +223,7 @@ function clabel(c) {
 // builder-start card (flat, 0.5px borders, CSS theme vars, Tabler icons, no
 // emoji); classes are `.st-*` so they can't collide with builder-start's `.bs-*`
 // or the ship card's `.cc-*`.
-const sesc = (s) => String(s == null ? '' : s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+const { escapeHtml: sesc } = require('../../src/html-escape'); // the one server escaper (task 1004876); it also escapes '
 
 // A value going inside a single-quoted JS string inside an HTML attribute needs
 // BOTH escapes, in that order. Task ids are digits so the existing handlers get

package/scripts/gds/escape-helper-guard.js

@@ -0,0 +1,6 @@
+// scripts/gds/escape-helper-guard.js — @bongos-forwarder (task 1004848). Generated by
+// scripts/bongos/codemod-rename-scripts-gds.js; do not edit.
+// The real script is scripts/bongos/escape-helper-guard.js. This forwarder keeps callers that still name
+// the old path working, and warns once so they get repointed. Task 1003706 removes it.
+'use strict';
+require('../bongos/forwarder.js').forward(module, 'escape-helper-guard.js');

package/scripts/status-mirror-sync.js

@@ -49,6 +49,7 @@ const { execFileSync } = require('node:child_process');
 const REPO_ROOT = path.resolve(__dirname, '..');
 const SRC = path.join(REPO_ROOT, 'modules', 'status-ui', 'public');
 const { branding, clientBranding, applyBrandConditionals } = require('../src/branding');
+const { escapeHtml } = require('../src/html-escape');
 
 // Stamp instance-identity tokens into the mirror HTML. The off-box mirror is
 // served by a static Pages host, NOT the branding-injecting Node server — so this
@@ -64,9 +65,7 @@ function brandTokens(html, brand = {}, publicOrigin = '', buildersOrigin = '') {
   const cur = (brand.currency && brand.currency.label) || 'credits';
   const Cur = cur ? cur.charAt(0).toUpperCase() + cur.slice(1) : cur;
   const company = (brand.identity && brand.identity.company) || {};
-  const esc = (s) => String(s == null ? '' : s)
-    .replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
-    .replace(/"/g, '&quot;').replace(/'/g, '&#39;');
+  const esc = escapeHtml; // the one server escaper (task 1004876)
   return applyBrandConditionals(html, { companyName: company.name, companySite: company.site, companyTagline: company.tagline })
     .split('{{worldName}}').join(esc(world))
     .split('{{productName}}').join(esc(product))

package/src/bongos/module-scope-map.js

@@ -464,6 +464,7 @@ const MODULE_GLOBS = {
     'scripts/bongos/route-shadow-guard.js', 'scripts/bongos/routine-schedule.js',
     'scripts/bongos/seam-wiring-guard.js', 'scripts/bongos/skill-preflight.js',
     'scripts/bongos/test-path-guard.js', 'scripts/bongos/version-literal-guard.js', 'scripts/bongos/dev-box-guard.js',
+    'scripts/bongos/escape-helper-guard.js', // task 1004876
   
     // ADOPTED (task 1004111): the enforcement surfaces this module already IS.
     // install-git-hooks.js + scripts/bongos/hooks/ are the pre-push hook beside the

package/src/bongos/platform-visibility-gate.js

@@ -177,9 +177,8 @@ function relativeReturn(raw) {
   return raw === '/' ? null : raw;
 }
 
-function escAttr(s) {
-  return String(s).replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
-}
+// The one server escaper (task 1004876); it also escapes ' , which this copy did not.
+const { escapeHtml: escAttr } = require('../html-escape');
 
 // The door. Self-contained on purpose (the pre-launch gate's shape): it is
 // served to someone who may not see the project, so it pulls no stylesheet, no

package/src/bongos/prelaunch-gate.js

@@ -180,9 +180,8 @@ function relativeReturn(raw) {
   return raw;
 }
 
-function escAttr(s) {
-  return String(s).replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
-}
+// The one server escaper (task 1004876); it also escapes ' , which this copy did not.
+const { escapeHtml: escAttr } = require('../html-escape');
 
 // The form. Self-contained and token-free on purpose: it is served BEFORE the
 // visitor is allowed to see anything, so it must not pull the branding bundle,

package/src/bongos/routes/auth.js

@@ -44,11 +44,7 @@ const seams = require('../../module-seams');
 // the kernel logger directly; only MODULES go via api.logger (the doorway).
 const log = require('../logger').logger.child({ src: 'auth' });
 
-function escapeHtml(s) {
-  return String(s ?? '').replace(/[&<>"']/g, (c) => ({
-    '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;',
-  }[c]));
-}
+const { escapeHtml } = require('../../html-escape'); // the one server escaper (task 1004876)
 
 // Render a small standalone HTML page in the builders' hall palette. Used for
 // OAuth error branches so the visitor sees something coherent rather than a

package/src/bongos/serve-internal.js

@@ -264,12 +264,8 @@ function dropEmptyHrefLinks(html, values) {
 // No token is ever emitted into a <script> or a CSS context (checked across
 // public-landing/, hall-ui/, status-ui/ — all under modules/ since task 1003322)
 // — that would need different escaping.
-// Ampersand first, or the other replacements get double-escaped.
-function esc(s) {
-  return String(s == null ? '' : s)
-    .replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
-    .replace(/"/g, '&quot;').replace(/'/g, '&#39;');
-}
+// The one server escaper (src/html-escape.js, task 1004876).
+const { escapeHtml: esc } = require('../html-escape');
 // The instance apex origin from the full branding pack (domains is server-only,
 // so it never rides clientBranding). Best-effort so a branding hiccup can't crash
 // serving.

package/src/html-escape.js

@@ -0,0 +1,26 @@
+// src/html-escape.js — THE server-side HTML escaper (task 1004876, goal 1000135).
+//
+// Escapes the five characters that let text become markup — & < > " ' — so a
+// builder's own words (a task title, an error detail, a project name) stay text
+// when they are written into a page, an attribute or an email. null and
+// undefined render as empty text; anything else is String()-ed first.
+//
+// ONE copy per side, on purpose. The browser twin is window.OTB.escapeHtml in
+// modules/hall-ui/public/dom-utils.js and the two must agree on every input
+// (tests/html_escape.mjs runs both). Modules reach this one through the doorway
+// (`api.escapeHtml`, src/module-api.js — ADR 0083); core files and scripts
+// require it directly. scripts/bongos/escape-helper-guard.js fails fitness on a
+// third hand-rolled copy anywhere in the code.
+//
+// Zero dependencies by design: the CLI requires it, so it must cost nothing to load.
+
+'use strict';
+
+const TABLE = { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' };
+
+/** HTML-escape `s` for text or a quoted attribute value. null/undefined → ''. */
+function escapeHtml(s) {
+  return String(s ?? '').replace(/[&<>"']/g, (c) => TABLE[c]);
+}
+
+module.exports = { escapeHtml };

package/src/module-api.js

@@ -57,6 +57,10 @@ const { buildInfo } = require('./build-info');
 // (`responsibilitiesFor` via src/modules.js, `ROLE_RESPONSIBILITIES` via
 // scripts/bongos/gen-role-responsibilities.js) were never flagged and this one was.
 const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibilities');
+// Eager and destructured for the same reasons: html-escape.js requires nothing.
+// escapeHtml is THE server-side HTML escaper (task 1004876) — a module renders
+// user text into a page through this, never through a private copy.
+const { escapeHtml } = require('./html-escape');
 
 // ---------------------------------------------------------------------------
 // CORE_VERSION — the version of THIS published surface (semver).
@@ -75,7 +79,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // MAJOR (see allowBoxScope below): passes the request through untouched.
 function deprecatedNoopMiddleware(_req, _res, next) { next(); }
 
-const CORE_VERSION = '1.21.182'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.22.2'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('discord'); log.info('mounted');
@@ -122,6 +126,10 @@ function logger(moduleKey) {
 module.exports = {
   CORE_VERSION,
 
+  // escapeHtml(s) — the one server-side HTML escaper (& < > " '; null → ''). The
+  //     browser twin is window.OTB.escapeHtml; fitness fails on a third copy (task 1004876).
+  escapeHtml,
+
   // --- auth & rank (ADR 0016) — the gates the loader composes around a module's
   //     routes; a module declares the rank it needs and never wires auth itself.
   get requireBuilder() { return require('./bongos/auth').requireBuilder; },

package/tests/blockers_kit_pager.mjs

@@ -22,7 +22,7 @@ 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, realOTB } from './helpers.mjs';
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const read = (rel) => fs.readFileSync(path.join(ROOT, rel), 'utf8');
@@ -97,7 +97,7 @@ function harness({ total = 57, failAfter = null, perPagePref = null } = {}) {
       getItem: (k) => (store.has(k) ? store.get(k) : null),
       setItem: (k, v) => store.set(k, String(v)),
     },
-    OTB: { toast: (msg) => toasts.push(msg) },
+    OTB: { ...realOTB(), toast: (msg) => toasts.push(msg) },
     addEventListener() {},
     // loadViewer() calls this for GET /me; signed-out (401) keeps isReviewer()
     // false, which is fine for these paging tests — they don't inspect the

package/tests/blockers_page_ui.mjs

@@ -26,7 +26,7 @@ import path from 'node:path';
 import vm from 'node:vm';
 import { fileURLToPath } from 'node:url';
 import { createRequire } from 'node:module';
-import { makeRunner, makeEl, walk } from './helpers.mjs';
+import { makeRunner, makeEl, walk, realOTB } from './helpers.mjs';
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const HALL = path.join(ROOT, 'modules/hall-ui/public');
@@ -114,7 +114,7 @@ async function boot(opts = {}) {
     getElementById(id) { return walk(root, (el) => (el.id === id ? el : null)); },
   };
   const windowObj = {
-    OTB: { toast: (m) => toasts.push(m) },
+    OTB: { ...realOTB(), toast: (m) => toasts.push(m) },
     OTBBlockersLib,
     OTBTaskDetail: { href: (id) => '/task/' + id },
     BongosClient: { createClient: () => api },

package/tests/core_move_notice.mjs

@@ -15,6 +15,7 @@ import path from 'node:path';
 import vm from 'node:vm';
 import { fileURLToPath } from 'node:url';
 import { createRequire } from 'node:module';
+import { realOTB } from './helpers.mjs';
 
 const require = createRequire(import.meta.url);
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
@@ -233,6 +234,7 @@ function boot({ data, permissions = { 'core.pin.move': true }, stored = {} } = {
   };
   const location = { hostname: 'h', origin: 'https://h', pathname: '/', hash: '', assign() {}, replace() {} };
   const windowObj = {
+    OTB: realOTB(), // the page loads dom-utils.js first (task 1004876)
     __BRANDING__: {}, __MODULES__: { enabled: { provisioning: false } },
     BongosClient: { createClient: () => ({ request: (method, p, opts) => {
       requested.push({ method, p, body: opts && opts.body });
@@ -313,7 +315,7 @@ async function panel(data) {
   const el = () => ({ hidden: true, textContent: '', _html: '', dataset: {}, set innerHTML(v) { this._html = String(v); }, get innerHTML() { return this._html; }, querySelectorAll: () => [] });
   const els = new Map([['software-update-scroll', el()], ['su-body', el()], ['su-note', el()], ['settings-groups', el()]]);
   els.get('settings-groups').dataset.active = 'update';
-  const windowObj = { BongosClient: { createClient: () => ({ request: async () => ({ ok: true, status: 200, data }) }) }, OTB: { escapeHtml }, location: { assign() {} } };
+  const windowObj = { BongosClient: { createClient: () => ({ request: async () => ({ ok: true, status: 200, data }) }) }, OTB: { ...realOTB(), escapeHtml }, location: { assign() {} } };
   const sandbox = { window: windowObj, document: { getElementById: (id) => els.get(id) || null, addEventListener() {} }, console, setTimeout, Date, Math, URL, Promise, String, Number };
   vm.createContext(sandbox);
   vm.runInContext(PANEL_SRC, sandbox, { filename: 'settings-software-update.js' });

package/tests/core_update_banner.mjs

@@ -12,6 +12,7 @@ import path from 'node:path';
 import vm from 'node:vm';
 import { createRequire } from 'node:module';
 import { fileURLToPath } from 'node:url';
+import { realOTB } from './helpers.mjs';
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const require_ = createRequire(import.meta.url);
@@ -265,6 +266,7 @@ function boot({ permissions, update, status = 200, dismissed = null, provisionin
   };
   const location = { hostname: 'h', origin: 'https://h', pathname, hash: '', assign() {}, replace() {} };
   const windowObj = {
+    OTB: realOTB(), // the page loads dom-utils.js first (task 1004876)
     __BRANDING__: {}, __MODULES__: { enabled: { provisioning } },
     BongosClient: {
       createClient: () => ({

package/tests/core_upgrade_owner_door.mjs

@@ -23,6 +23,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import vm from 'node:vm';
 import { fileURLToPath } from 'node:url';
+import { realOTB } from './helpers.mjs';
 
 const require = createRequire(import.meta.url);
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
@@ -409,6 +410,7 @@ function boot({ provisioning, deployUrl, pathname = '/settings', hash = '', held
   const location = { hostname: 'h', origin: 'https://h', pathname, hash, assign() {}, replace() {} };
   const update = { running: '1.19.871', latest: '1.19.1033', behind: true, reading: 'ok' };
   const windowObj = {
+    OTB: realOTB(), // the page loads dom-utils.js first (task 1004876)
     __BRANDING__: {}, __MODULES__: { enabled: { provisioning } },
     BongosClient: {
       createClient: () => ({

package/tests/craft_mode.mjs

@@ -14,6 +14,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import vm from 'node:vm';
 import { fileURLToPath } from 'node:url';
+import { realOTB } from './helpers.mjs';
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const HALL = path.join(ROOT, 'modules/hall-ui/public');
@@ -115,6 +116,7 @@ function boot({ craft = true, session = {}, store = {}, throws = false, optOut =
     removeItem: (k) => { if (throws) throw new Error('SecurityError'); delete obj[k]; },
   });
   const windowObj = {
+    OTB: realOTB(), // the page loads dom-utils.js first (task 1004876)
     __BRANDING__: {}, __MODULES__: { enabled: {} },
     BongosClient: { createClient: () => ({ request: () => new Promise(() => {}) }) },
     matchMedia: (q) => ({ matches: narrow && /max-width: 640px/.test(q), addEventListener() {} }),

package/tests/craft_mode_nav.mjs

@@ -14,6 +14,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import vm from 'node:vm';
 import { fileURLToPath } from 'node:url';
+import { realOTB } from './helpers.mjs';
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const HALL = path.join(ROOT, 'modules/hall-ui/public');
@@ -90,6 +91,7 @@ function boot({ session = {}, perms = { 'board.vote.cast': true } } = {}) {
   const location = { hostname: 'h', origin: 'https://h', href: 'https://h/work', pathname: '/work', hash: '', search: '', assign() {}, replace() {}, reload() {} };
   const mk = (obj) => ({ getItem: (k) => (k in obj ? obj[k] : null), setItem: (k, v) => { obj[k] = String(v); }, removeItem: (k) => { delete obj[k]; } });
   const windowObj = {
+    OTB: realOTB(), // the page loads dom-utils.js first (task 1004876)
     __BRANDING__: {}, __MODULES__: { enabled: { provisioning: true } },
     BongosClient: { createClient: () => ({ request: () => new Promise(() => {}) }) },
     matchMedia: () => ({ matches: false, addEventListener() {} }),
@@ -274,6 +276,7 @@ function bootTree({ mode = null, activeId = null } = {}) {
     addEventListener() {}, removeEventListener() {},
   };
   const windowObj = {
+    OTB: realOTB(), // the page loads dom-utils.js first (task 1004876)
     location: { search: '' }, matchMedia: () => ({ matches: false }),
     localStorage: mk({}), sessionStorage: mk(mode ? { 'hall-craft': mode } : {}),
   };

package/tests/craft_review_mode.mjs

@@ -13,6 +13,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import vm from 'node:vm';
 import { fileURLToPath } from 'node:url';
+import { realOTB } from './helpers.mjs';
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const HALL = path.join(ROOT, 'modules/hall-ui/public');
@@ -77,7 +78,7 @@ function boot({ session = {}, store = {}, narrow = false } = {}) {
     dispatchEvent() { return true; },
   };
   const mk = (obj) => ({ getItem: (k) => (k in obj ? obj[k] : null), setItem: (k, v) => { obj[k] = String(v); }, removeItem: (k) => { delete obj[k]; } });
-  const window = { localStorage: mk(store), sessionStorage: mk(session), matchMedia: (q) => ({ matches: narrow && /max-width: 640px/.test(q) }), location: { search: '' } };
+  const window = { OTB: realOTB(), localStorage: mk(store), sessionStorage: mk(session), matchMedia: (q) => ({ matches: narrow && /max-width: 640px/.test(q) }), location: { search: '' } };
   const sandbox = { window, document, Promise, setTimeout, clearTimeout, CustomEvent: class { constructor(t, i) { this.type = t; Object.assign(this, i); } } };
   vm.createContext(sandbox);
   // "Loading" a script: the wall runs the REAL craft-review.js; the palette is a fake panel.
@@ -208,7 +209,7 @@ test('THE WALL is scribbled in CSS only, in ink alone, and stands still under re
 });
 
 test('craft-review.js draws six small sky doodles, each with its pen, the wide ones foldable', () => {
-  const sandbox = { window: {} };
+  const sandbox = { window: { OTB: realOTB() } };
   vm.createContext(sandbox);
   vm.runInContext(REVIEW, sandbox);
   const api = sandbox.window.OTBCraftReview;

package/tests/criterion_ref_status.mjs

@@ -194,8 +194,13 @@ test('a slug carrying an apostrophe cannot break the click handler', () => {
   // single-quoted JS string inside an HTML attribute.
   const odd = { ...crit(2, "o'hara-rule", '1000999') };
   const html = status.renderStatusWidget({ ...DATA, criteria: [odd] }, null);
-  assert.ok(html.includes("sendPrompt('/status o\\'hara-rule')"),
-    'the apostrophe was not escaped for the JS string');
+  // The attribute is HTML-escaped AFTER the JS escape, so the apostrophe arrives as
+  // \' (task 1004876: the shared escaper escapes ' too) — the browser decodes the
+  // attribute first, and the JS it then parses is the \' asserted below.
+  const onclick = html.match(/onclick="([^"]*o\\'hara-rule[^"]*)"/);
+  assert.ok(onclick, 'the apostrophe was not escaped for the JS string');
+  assert.ok(onclick[1].replace(/'/g, "'").includes("sendPrompt('/status o\\'hara-rule')"),
+    'the decoded handler carries the JS-escaped apostrophe');
 });
 
 console.log(`\ncriterion ref — read side (task 1004069): ${passed} passed, ${failed} failed`);

package/tests/curve_kind_overlay.mjs

@@ -26,12 +26,13 @@ import fs from 'node:fs';
 import path from 'node:path';
 import vm from 'node:vm';
 import { fileURLToPath } from 'node:url';
+import { realOTB } from './helpers.mjs';
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 
 function loadKit() {
   const src = fs.readFileSync(path.join(ROOT, 'modules/hall-ui/public/hall-kit.js'), 'utf8');
-  const win = {};
+  const win = { OTB: realOTB() }; // the page loads dom-utils.js first (task 1004876)
   const ctx = vm.createContext({ window: win, document: { createElement: () => ({}) }, console });
   vm.runInContext(src, ctx);
   assert.ok(win.OTBKit, 'hall-kit.js did not publish window.OTBKit');

package/tests/founding_mode.mjs

@@ -13,6 +13,7 @@ import { createRequire } from 'node:module';
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { realOTB } from './helpers.mjs';
 
 const require = createRequire(import.meta.url);
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
@@ -135,6 +136,13 @@ function makeHall() {
 
 // The REAL escaper and the real wake map are sliced out of shell.js with the function,
 // so the band's escaping is the shell's own, not a stand-in that agrees with the test.
+// shell.js escapes through window.OTB (dom-utils.js, task 1004876), so the window it is
+// handed carries the real one.
+function sliceEsc() {
+  const line = SHELL.split("\n").find((l) => l.startsWith("  function esc("));
+  assert.ok(line, "esc was located in shell.js");
+  return line;
+}
 function sliceFn(name) {
   const start = SHELL.indexOf('  function ' + name + '(');
   const end = SHELL.indexOf('\n  }\n', start);
@@ -145,8 +153,8 @@ function loadApplyFounding(document, access, brand = { identity: { productName:
   const wakeStart = SHELL.indexOf('  var WAKE_TEXT = {');
   const wakeEnd = SHELL.indexOf('};', wakeStart) + 2;
   assert.ok(wakeStart > -1, 'WAKE_TEXT was located in shell.js');
-  const src = [SHELL.slice(wakeStart, wakeEnd), sliceFn('esc'), sliceFn('applyFounding')].join('\n');
-  return new Function('document', 'brand', 'access', `${src}\nreturn applyFounding;`)(document, brand, access);
+  const src = [SHELL.slice(wakeStart, wakeEnd), sliceEsc(), sliceFn('applyFounding')].join('\n');
+  return new Function('document', 'brand', 'access', 'window', `${src}\nreturn applyFounding;`)(document, brand, access, { OTB: realOTB() });
 }
 
 const snapshot = (h) => JSON.stringify({

package/tests/github_install_nudge.mjs

@@ -22,6 +22,7 @@ import path from 'node:path';
 import vm from 'node:vm';
 import { createRequire } from 'node:module';
 import { fileURLToPath } from 'node:url';
+import { realOTB } from './helpers.mjs';
 
 const require = createRequire(import.meta.url);
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
@@ -159,12 +160,14 @@ test('GET /provisioning/instances and /provisioning/instances/:id carry github_i
 function grab(head) {
   const at = HUB.indexOf(`\n  ${head}`);
   assert.ok(at >= 0, `${head} must exist`);
+  const line = HUB.slice(at, HUB.indexOf('\n', at + 1));
+  if (/\}\s*$/.test(line)) return line; // a one-line declaration (esc, task 1004876)
   const end = HUB.indexOf('\n  }', at + 1);
   const close = HUB.slice(end, end + 5) === '\n  };' ? end + 5 : end + 4;
   return HUB.slice(at, close);
 }
 function page() {
-  const ctx = { STATE_GROUP: { active: 'live', error: 'attention', torn_down: 'gone' } };
+  const ctx = { window: { OTB: realOTB() }, STATE_GROUP: { active: 'live', error: 'attention', torn_down: 'gone' } };
   vm.createContext(ctx);
   vm.runInContext(['function esc(', 'function ghInstallRow(', 'function groupFor('].map(grab).join('\n'), ctx);
   return ctx;

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) => !['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']);
+  assert.deepEqual(scripts(html).filter((s) => !['dom-utils.js', '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) => !['shell-trail.js', 'craft-mode.js', 'shell.js'].includes(s[0]));
+  const skyScripts = (h) => scripts(h).filter((s) => !['dom-utils.js', '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_approval_queue.mjs

@@ -18,7 +18,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import vm from 'node:vm';
 import { fileURLToPath } from 'node:url';
-import { makeRunner, makeEl, walk, settle } from './helpers.mjs';
+import { makeRunner, makeEl, walk, settle, realOTB } from './helpers.mjs';
 
 const require = createRequire(import.meta.url);
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
@@ -105,7 +105,7 @@ function bootPanel({ answers = {}, writes = null, mode = 'light' } = {}) {
       return val.__status ? { ok: false, status: val.__status, data: val.data } : { ok: true, status: 200, data: val };
     },
   };
-  const win = { matchMedia: () => ({ matches: false }), __BRANDING__: { identity: { productName: 'Cloud Bongos', worldName: 'the studio' } } };
+  const win = { OTB: realOTB(), matchMedia: () => ({ matches: false }), __BRANDING__: { identity: { productName: 'Cloud Bongos', worldName: 'the studio' } } };
   const ctx = vm.createContext({ window: win, document: documentObj, console, setTimeout, clearTimeout, encodeURIComponent });
   win.window = win;
   vm.runInContext(read('brand-holes.js'), ctx, { filename: 'brand-holes.js' });

package/tests/hall_city.mjs

@@ -288,7 +288,7 @@ test('the city sits in the hall chrome, behind the shell\'s full-screen switch',
   // task 1004685 (the living city): gov-living.js, the model under the drawing, and
   // gov-feeds.js, its one reader per page (shared with the shell's tally), load before it
   // task 1004702: the card answers its first ask in place, so the deck's card and sender (and the desk rows under them) load before the page
-  assert.deepEqual(scripts, ['shell-trail', 'craft-mode', 'shell', 'palette', 'gov-living', 'gov-feeds', 'city-draw', 'hall-kit', 'street-draw', 'street-card', 'street-inside', 'street-desk', 'street-deck', 'city-decide', 'city-switchboard', 'city'], 'the shell first, as on every hall page');
+  assert.deepEqual(scripts, ['dom-utils', 'shell-trail', 'craft-mode', 'shell', 'palette', 'gov-living', 'gov-feeds', 'city-draw', 'hall-kit', 'street-draw', 'street-card', 'street-inside', 'street-desk', 'street-deck', 'city-decide', 'city-switchboard', '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

@@ -18,6 +18,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import vm from 'node:vm';
 import { fileURLToPath } from 'node:url';
+import { realOTB } from './helpers.mjs';
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const HALL = path.join(ROOT, 'modules/hall-ui/public');
@@ -104,6 +105,7 @@ function boot({ page = 'thinking', optIn = true, store = {}, storageThrows = fal
   };
   let resizes = 0;
   const windowObj = {
+    OTB: realOTB(), // the page loads dom-utils.js first (task 1004876)
     __BRANDING__: {}, __MODULES__: { enabled: {} },
     // `meId` answers /me once with that builder; otherwise the read never settles.
     BongosClient: { createClient: () => ({ request: () => (meId == null ? new Promise(() => {})

package/tests/hall_gov_real_site.mjs

@@ -31,6 +31,7 @@ import path from 'node:path';
 import vm from 'node:vm';
 import { createRequire } from 'node:module';
 import { fileURLToPath } from 'node:url';
+import { realOTB } from './helpers.mjs';
 
 const require = createRequire(import.meta.url);
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
@@ -300,6 +301,7 @@ function baseWindow(hash = '') {
   const store = new Map();
   const ls = { getItem: (k) => (store.has(k) ? store.get(k) : null), setItem: (k, v) => store.set(k, String(v)), removeItem: (k) => store.delete(k) };
   return {
+    OTB: realOTB(), // the page loads dom-utils.js first (task 1004876)
     innerWidth: 1440, innerHeight: 900, location: { hash, href: '', search: '', pathname: '/' },
     localStorage: ls, sessionStorage: ls,
     matchMedia: () => ({ matches: true, addEventListener() {} }), addEventListener() {}, removeEventListener() {},

package/tests/hall_kit_charts.mjs

@@ -20,6 +20,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import vm from 'node:vm';
 import { fileURLToPath } from 'node:url';
+import { realOTB } from './helpers.mjs';
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const HALL = path.join(ROOT, 'modules', 'hall-ui', 'public');
@@ -299,7 +300,7 @@ function runPage(file, extraWindow = {}) {
     { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]));
   const sandbox = {
     window: {
-      OTB: { escapeHtml: esc, $: () => null, fmtNum: (n) => String(n ?? 0), fmtDate: (s) => String(s ?? '') },
+      OTB: { ...realOTB(), escapeHtml: esc, $: () => null, fmtNum: (n) => String(n ?? 0), fmtDate: (s) => String(s ?? '') },
       __BRANDING__: { currency: { label: 'drachmae' } },
       ...extraWindow,
     },

package/tests/hall_my_agents.mjs

@@ -26,6 +26,7 @@ import path from 'node:path';
 import vm from 'node:vm';
 import { createRequire } from 'node:module';
 import { fileURLToPath } from 'node:url';
+import { realOTB } from './helpers.mjs';
 
 const require = createRequire(import.meta.url);
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
@@ -378,7 +379,7 @@ function bootCraft({ session = {} } = {}) {
     getElementById: () => null, querySelector: () => null, querySelectorAll: () => [],
     createElement: () => el(), addEventListener() {}, removeEventListener() {}, dispatchEvent() { return true; },
   };
-  const window = { location: { search: '' }, matchMedia: () => ({ matches: false }), sessionStorage: mk(session), localStorage: mk({}) };
+  const window = { OTB: realOTB(), location: { search: '' }, matchMedia: () => ({ matches: false }), sessionStorage: mk(session), localStorage: mk({}) };
   const sandbox = { window, document, console, CustomEvent: class { constructor(t, i) { this.type = t; Object.assign(this, i); } } };
   sandbox.globalThis = sandbox;
   vm.createContext(sandbox);
@@ -441,7 +442,7 @@ test('PAGE: in the hall family, with no prototype key', () => {
   const sheets = [...html.matchAll(/href="\/builders\/([a-z-]+\.css)/g)].map((m) => m[1]);
   assert.deepEqual(sheets, ['style.css', 'oversight.css', 'my-agents.css'], 'rides the oversight archetype, linked before its own sheet');
   const scripts = [...html.matchAll(/src="\/builders\/([a-z-]+)\.js/g)].map((m) => m[1]);
-  assert.deepEqual(scripts.slice(0, 3), ['shell-trail', 'craft-mode', 'shell']);
+  assert.deepEqual(scripts.slice(0, 4), ['dom-utils', 'shell-trail', 'craft-mode', 'shell']); // dom-utils first: the shell escapes through it (task 1004876)
   for (const s of ['gov-living', 'gov-positions', 'my-agents']) assert.ok(scripts.includes(s), `loads ${s}.js`);
   assert.doesNotMatch(html, /ma-key|data-proto|Prototype data/, 'nothing on the page is prototype data, so there is no key');
   assert.doesNotMatch(read('my-agents.js'), /governor-overlay/, 'and it reads no overlay');

package/tests/hall_nav.mjs

@@ -20,6 +20,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import vm from 'node:vm';
 import { fileURLToPath } from 'node:url';
+import { realOTB } from './helpers.mjs';
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const HALL = path.join(ROOT, 'modules/hall-ui/public');
@@ -136,6 +137,7 @@ function boot({ page = 'settings', hash = '', pathname = '/settings', search = '
   };
 
   const windowObj = {
+    OTB: realOTB(), // the page loads dom-utils.js first (task 1004876)
     __BRANDING__: {}, __MODULES__: { enabled: {} },
     // Index pages never reach probeMe (builders.js owns /me there); a non-index
     // boot would, so hand back a never-settling promise rather than fake auth —

package/tests/hall_palette.mjs

@@ -18,7 +18,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import vm from 'node:vm';
 import { fileURLToPath } from 'node:url';
-import { hallSource } from './helpers.mjs';
+import { hallSource, realOTB } from './helpers.mjs';
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const HALL = path.join(ROOT, 'modules/hall-ui/public');
@@ -79,7 +79,7 @@ function bootPalette({ navItems = [], visibleIds = ['nav-standing', 'nav-work',
     addEventListener() {},
     activeElement: null,
   };
-  const windowObj = { location: { hash: '', assign() {} }, addEventListener() {}, open() {} };
+  const windowObj = { OTB: realOTB(), location: { hash: '', assign() {} }, addEventListener() {}, open() {} };
   const sandbox = {
     window: windowObj, document: documentObj, navigator: { platform: 'Win32', userAgent: 'test' },
     console, setTimeout, clearTimeout, Promise, JSON, Number, String, Array, Object,