@bongos/core 1.25.1 → 1.25.2

package/.bongos-core.json

@@ -2,11 +2,11 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/bongos/package-core.js",
-  "core_version": "1.25.1",
-  "core_contract": "1.25.1",
-  "source_commit": "ab6188463865682dcca46f3680eb50a3227322d9",
+  "core_version": "1.25.2",
+  "core_contract": "1.25.2",
+  "source_commit": "dc57adbfa99c5fe357e8cf6722c5706199587d8a",
   "source_ref": "HEAD",
-  "built_at": "2026-11-12T21:45:21.690Z",
+  "built_at": "2026-11-12T23:01:13.126Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 654,
@@ -17,7 +17,7 @@
     "gate": "passed"
   },
   "file_count": 4676,
-  "tree_sha256": "bdaeb36c9c1b8bff0272eae34c82d2a800abec3856f9eeebe36a61d0f35d6b3f",
+  "tree_sha256": "80c07d7b3023e83808ed7dc00f57b85a1c44550f7fd2b51df0d44c924dd5f2ad",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -2527,12 +2527,12 @@
     {
       "path": "docs/copy-inventory.md",
       "mode": "0000644",
-      "sha256": "94fedf8bca9d202551ac01582ae236b9fc3d4dd38805f079023b8c61dab8c34a"
+      "sha256": "0466e87434c29e6c17fc74c146a7ecf5c2d795e6817c5a8870df0cb704373c52"
     },
     {
       "path": "docs/copy-registry.json",
       "mode": "0000644",
-      "sha256": "3b9b2e2d1549748d240c2de55c53e8a8440241581a3cc848554993303dda3c5f"
+      "sha256": "ad843392d336c5e2f459411b80e8426e9d8c7d0ffb1bd7cd60dc076c5a3cfc4e"
     },
     {
       "path": "docs/design/apex-pass-2-direction.md",
@@ -3087,7 +3087,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "5cbde19ec7bd628215e624bd4e1d5396d42b25d9db77c511e93884a79a00d062"
+      "sha256": "1d1d128fddc2d52abe04ec70862a0f5cfda31ceb6e2e266630c140402e30830a"
     },
     {
       "path": "docs/modules-contract.md",
@@ -3172,7 +3172,7 @@
     {
       "path": "docs/page-readings.json",
       "mode": "0000644",
-      "sha256": "e45541ce7f58c185af5290f210c3e6e1fec64ae19a4e2b9336ab9d1c2021b3d9"
+      "sha256": "8d1710ac1c1a2e954e990604fa84ca6d8473b775affce45227159d992566017e"
     },
     {
       "path": "docs/project-context.template.md",
@@ -7547,7 +7547,7 @@
     {
       "path": "modules/hall-ui/public/visor.js",
       "mode": "0000644",
-      "sha256": "4bf7299fd961c12f15e355b9898d779c0c4a3f258817fd712ec12d1a2d70fb6a"
+      "sha256": "b5e10f04166881ad0301873d165da1a6f6500b37685a0ac565c2c500705f0470"
     },
     {
       "path": "modules/hall-ui/public/vote-control.js",
@@ -7867,7 +7867,7 @@
     {
       "path": "modules/hall-ui/records/visor.md",
       "mode": "0000644",
-      "sha256": "e8392fa5d8ec56cffd336101ed8a247b377be8172cea7d54e40c887548114607"
+      "sha256": "19c6509e448da3b561a78aaa18bc2b301ed2443ef154ce1626f98fb7fd9287a8"
     },
     {
       "path": "modules/hall-ui/records/welcome-tower.md",
@@ -12217,12 +12217,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "91918d6ff38e731f24ee145f1ac45ad79aeae24a1f748d538fd229dc129d517e"
+      "sha256": "5d2513f948e7a8850de02637e4484ede6f5179c86b04865397d95182d8d276b2"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "6d0090ccb1cf713ca96875e4acc6f4af8ab030650a847404825d78c8642c0abd"
+      "sha256": "427c5862690dc27e7d377994e6168ac30cc09bca716565934fc62f8c305e4b0e"
     },
     {
       "path": "public-docs/index.html",
@@ -12242,7 +12242,7 @@
     {
       "path": "release-notes.json",
       "mode": "0000644",
-      "sha256": "9a01a7a0d535adb2c9804def7bf85a89ef6343277e4d71d5891168d18fac0f2c"
+      "sha256": "6903717372407e77f5a906d0dcd4b06d8aa21dd10255a19a5602228c714a3457"
     },
     {
       "path": "scripts/bongos/CLAUDE.md",
@@ -16252,7 +16252,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "39c65d85a20b2b575503327d65f70039e139827031595d85ded7b9228477ff8b"
+      "sha256": "83df2597f55dcfbaf89dde346ad6e2a3b697b254a1cb00e985cc3d94df7adece"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -19522,7 +19522,7 @@
     {
       "path": "tests/hall_visor.mjs",
       "mode": "0000644",
-      "sha256": "48de1d859b2e3dacb7f8aa693e55b405923c65621bd995278af4227861099290"
+      "sha256": "da366a1781b96c82152232b8e63a594609609e309336e36bf4d69cf80090b24f"
     },
     {
       "path": "tests/hall_work_history_id.mjs",

package/docs/copy-inventory.md

@@ -316,7 +316,7 @@ Identical copy within one surface. Sometimes right (a repeated button), sometime
 | `4df46e2be815` | certain | Clear the key? | `modules/hall-ui/public/market-watch-settings.js:218` |
 | `593dda3178eb` | certain | Click to copy | `modules/hall-ui/public/copy-on-click.js:137` |
 | `34624d39ff29` | certain | Clone the project to your machine and run | `modules/hall-ui/public/setup-gate.js:34` |
-| `3a426bad2c49` | certain | Close actions | `modules/hall-ui/public/visor.js:293` |
+| `3a426bad2c49` | certain | Close actions | `modules/hall-ui/public/visor.js:336` |
 | `70f6a704d504` | certain | Close it | `modules/hall-ui/public/copy-desk.html:140` |
 | `053e576ba9a3` | certain | Close options | `modules/hall-ui/public/shell-game.js:454` |
 | `d12a2fb5730d` | certain | Close this flag | `modules/hall-ui/public/copy-desk.html:116` |
@@ -1486,7 +1486,7 @@ Identical copy within one surface. Sometimes right (a repeated button), sometime
 | `9a685b01e2c6` | certain | This page opens at a higher rank. | `modules/hall-ui/public/watch.html:237` |
 | `e7a289134dc3` | certain | This page shows no words the reader could find. | `modules/hall-ui/public/tweak-editor.js:246` |
 | `d4b3b5556986` | certain | This page's reference docs | `modules/hall-ui/public/page-notes.js:166` |
-| `79e4a934b434` | certain | This place | `modules/hall-ui/public/visor.js:295` |
+| `79e4a934b434` | certain | This place | `modules/hall-ui/public/visor.js:338` |
 | `5bdcbec770dd` | certain | This project has no slash commands yet. | `modules/hall-ui/public/commands.js:37` |
 | `f53b83bfbe54` | certain | This project has no watch rules yet. | `modules/hall-ui/public/market-watch-rules.js:62` |
 | `e97b2d549f10` | certain | This project is hosted on {…}, and that is where it is taken offline or removed. Both links below open this pr | `modules/hall-ui/public/project-settings.js:412` |

package/docs/copy-registry.json

@@ -5208,7 +5208,7 @@
       "surface": "builders-hall",
       "text": "Close actions",
       "file": "modules/hall-ui/public/visor.js",
-      "line": 293,
+      "line": 336,
       "origin": "js-markup",
       "confidence": "certain"
     },
@@ -15738,7 +15738,7 @@
       "surface": "builders-hall",
       "text": "This place",
       "file": "modules/hall-ui/public/visor.js",
-      "line": 295,
+      "line": 338,
       "origin": "js-markup",
       "confidence": "certain"
     },

package/docs/module-api-changelog.md

@@ -3444,5 +3444,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         after its permission gate (task 1004747, ADR 0382). Additive, so MINOR.
   1.25.1 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.25.0 with no explicit bump. run 43313162829. (task 1002620)
+  1.25.2 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.25.1 with no explicit bump. run 43325008692. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/docs/page-readings.json

@@ -283,7 +283,7 @@
       "surface": "builders",
       "title": "The city",
       "states_read": ["city","fullscreen","focus","pins","living","card","card-ask"],
-      "files_hash": "0367a0e57f2fcfb1",
+      "files_hash": "573bb0fbcdcafa9a",
       "reading_hash": "277096d903879a57",
       "counts": {"lines":26,"placed":9,"shared":6,"unplaced":11},
       "omitted": {"data":7},
@@ -613,7 +613,7 @@
       "surface": "builders",
       "title": "The sky",
       "states_read": ["tour","sky","wells","ledger","full","full-back","out"],
-      "files_hash": "9de2854d844d990f",
+      "files_hash": "fe5e504a7e12bca9",
       "reading_hash": "4a879397a84631e3",
       "counts": {"lines":50,"placed":25,"shared":6,"unplaced":19},
       "omitted": {"data":10},
@@ -954,8 +954,8 @@
       "surface": "builders",
       "title": "Builders' Hall",
       "states_read": ["home","out","founding","genesis","decide","demo"],
-      "files_hash": "36c7410d9c8aeae0",
-      "reading_hash": "45468116976bf674",
+      "files_hash": "b3b116e114d183f4",
+      "reading_hash": "59797028e6124c9c",
       "counts": {"lines":32,"placed":12,"shared":8,"unplaced":12},
       "omitted": {"data":5},
       "notes": ["founding: an action failed (page.focus: Timeout 6000ms exceeded.); read as it stood"],
@@ -977,7 +977,7 @@
         {"key":"L0015","section":"Needs your attention13","text":"Ideas awaiting triage","placement":"placed","file":"modules/hall-ui/public/builders.js","line":320,"string_id":"e181637c5a5e"},
         {"key":"L0016","section":"Needs your attention13","text":"Requires project {…} fix","placement":"unplaced"},
         {"key":"L0017","section":"footer","text":"Sign out","placement":"shared","file":"modules/hall-ui/public/shell.js","line":514,"string_id":"1883ad7f07fc"},
-        {"key":"L0018","section":"Needs your attention13","text":"core 1.24.94","placement":"unplaced"},
+        {"key":"L0018","section":"Needs your attention13","text":"core 1.25.1","placement":"unplaced"},
         {"key":"L0019","section":"Needs your attention13","text":"Skip","placement":"unplaced"},
         {"key":"L0020","section":"Needs your attention13","text":"Built on","placement":"placed","file":"modules/hall-ui/public/welcome-boot.js","line":183,"string_id":"fef59346ffee"},
         {"key":"L0021","section":"Needs your attention13","text":"cloudbongos.com","placement":"unplaced"},
@@ -3159,7 +3159,7 @@
       "surface": "builders",
       "title": "Your thinking",
       "states_read": ["tour","sky","list","simple","full-idea","full","full-list","full-back","out"],
-      "files_hash": "96c460b71d47125f",
+      "files_hash": "cd0f2d8f522becc8",
       "reading_hash": "b73f848b46b0f9b8",
       "counts": {"lines":50,"placed":25,"shared":6,"unplaced":19},
       "omitted": {"data":10},

package/modules/hall-ui/public/visor.js

@@ -11,9 +11,10 @@
 //     the character's colour; task 1005218), your character's name and your credits
 //     (builders.total_credits — credits only, never a payout; the spec's "does not exist").
 //     Centre: your character's main action, the one accent button, with its key. Right: the
-//     quiet key hints, no boxes: your other actions, "Actions" (key A), which opens the
-//     sheet (your character's actions, then the keys of the place you are in, then Options
-//     on Escape), and Options itself.
+//     quiet key hints, no boxes: your other actions and "Actions" (key A), which opens the
+//     sheet (your character's actions, then the keys of the place you are in, then Options on
+//     a key of its own; Escape closes it). Options is only in the sheet (task 1005248).
+//   - every key comes from resolveKeys: one owner per key, never two (task 1005248).
 //
 // The rules it keeps (ADR 0399):
 //   - one overlay, #visor, with pointer-events: none; only its controls take a pointer, so a
@@ -59,6 +60,11 @@
     ],
   };
   var SHEET_KEY = 'a';
+  var CLOSE_KEY = 'esc';   // shown once: the sheet's Close (Escape)
+  var OPTIONS = { id: 'options', label: 'Options', key: 'o', href: '/settings' };
+  // Keys a scene binds on its own page (the sky's L 0 / ?, the gallery's F, the palette's K).
+  // A moved key never lands on one of them; a scene that declares one keeps it.
+  var AVOID = ['l', '0', '/', '?', 'f', 'k', '+', '-', '='];
   var NAMES = { artisan: 'Artisan', artist: 'Artist', patron: 'Patron' };
 
   function esc(v) { return window.OTB && window.OTB.escapeHtml ? window.OTB.escapeHtml(v) : String(v == null ? '' : v).replace(/[^\w .,:'-]/g, ''); }
@@ -151,6 +157,42 @@
     render();
   }
 
+  // ---------- the keys: one resolver, so no key ever means two things (task 1005248) ----------
+  // Every key the visor shows or binds comes from here, and here hands each key out once.
+  // A key in ACTIONS or a scene's registration is a RECOMMENDATION: when it is already taken
+  // the action moves to the next free letter of its own name, then of the alphabet, and with
+  // none free it shows and binds no key at all. Never two owners. In order of who keeps a key:
+  //   1. the visor's own: A (Actions) and Escape (Close, while the sheet is open);
+  //   2. the keys a scene binds itself (an action without `bind`, and the `keys` lines): the
+  //      visor cannot move a key it does not bind, so a second claim on one shows no key;
+  //   3. the character's actions, in order; 4. the scene's `bind` actions; 5. Options.
+  function norm(k) { return k ? String(k).toLowerCase() : ''; }
+  function resolveKeys(id) {
+    var taken = {};
+    function claim(k, who) { if (!k || taken[k]) return ''; taken[k] = who; return k; }
+    function free(pref, label, who) {
+      var got = claim(norm(pref), who);
+      if (got || !pref) return got;
+      var pool = String(label || '').toLowerCase().replace(/[^a-z]/g, '') + 'abcdefghijklmnopqrstuvwxyz';
+      for (var i = 0; i < pool.length; i++) if (AVOID.indexOf(pool[i]) < 0 && claim(pool[i], who)) return pool[i];
+      return '';
+    }
+    claim(SHEET_KEY, 'sheet');
+    claim(CLOSE_KEY, 'close');
+    var sa = scene ? scene.actions : [], sk = scene ? scene.keys : [];
+    var place = sa.map(function () { return ''; });
+    sa.forEach(function (a, i) { if (!a.bind) place[i] = claim(norm(a.key), 'place:' + i); });
+    var lines = sk.map(function (k, i) { return claim(norm(k.key), 'line:' + i); });
+    var acts = actionsFor(id).map(function (a) {
+      var c = {}; for (var p in a) c[p] = a[p];
+      c.key = free(a.key, a.label, a.id);
+      return c;
+    });
+    sa.forEach(function (a, i) { if (a.bind) place[i] = free(a.key, a.label, 'place:' + i); });
+    var opts = { id: OPTIONS.id, label: OPTIONS.label, href: OPTIONS.href, key: free(OPTIONS.key, OPTIONS.label, OPTIONS.id) };
+    return { actions: acts, place: place, lines: lines, options: opts, taken: taken };
+  }
+
   // ---------- what the scene has picked (task 1005243) ----------
   // A scene that picks something (Home's tower) hands the visor a small card about it:
   // a title, one status, a few lines, and at most one action. The action becomes the
@@ -227,7 +269,7 @@
       svgOpen('visor__notch', '0 0 12 9') + twice('<path class="visor__line" d="M0 0l6 9l6 -9"/>') + '</svg>' +
       svgOpen('visor__sight', '0 0 24 24') + twice('<circle class="visor__line" cx="12" cy="12" r="11"/>') + '<circle class="visor__dot" cx="12" cy="12" r="2"/></svg>';
   }
-  function keyHtml(k) { k = String(k); return '<kbd class="visor__key">' + esc(k.length === 1 ? k.toUpperCase() : k) + '</kbd>'; }
+  function keyHtml(k) { k = String(k || ''); if (!k) return ''; if (k === CLOSE_KEY) k = 'Esc'; return '<kbd class="visor__key">' + esc(k.length === 1 ? k.toUpperCase() : k) + '</kbd>'; }
   // The count and its unit are two spans, so the number can be white and the word ice; the
   // text between them is still creditsText's, word for word.
   function creditsHtml(n) {
@@ -240,14 +282,14 @@
     return '<a class="visor__hint" data-visor-act="' + esc(a.id) + '" ' + actionAttrs(a) + '>' + keyHtml(a.key) + '<span>' + esc(a.label) + '</span></a>';
   }
   // The scene's lead action, as the first quiet hint (task 1005209).
-  function placeHintHtml(a, i) {
-    return '<button class="visor__hint visor__hint--place" type="button" data-visor-scene="' + i + '">' + (a.key ? keyHtml(a.key) : '') + '<span>' + esc(a.label) + '</span></button>';
+  function placeHintHtml(a, i, key) {
+    return '<button class="visor__hint visor__hint--place" type="button" data-visor-scene="' + i + '">' + keyHtml(key) + '<span>' + esc(a.label) + '</span></button>';
   }
   function actionAttrs(a) {
     return a.href ? 'href="' + esc(hallHref(a.href)) + '"' : 'href="#" role="button"';
   }
   function glassHtml(id) {
-    var acts = actionsFor(id), main = acts[0], C = craft();
+    var keys = resolveKeys(id), acts = keys.actions, main = acts[0], C = craft();
     // Your picture on the glass is you wearing the visor (task 1005218); an older craft-mode
     // without that picture still hands over the whole figure.
     var sprite = C && typeof C.portraitSrc === 'function' ? C.portraitSrc(id) : (C && typeof C.spriteSrc === 'function' ? C.spriteSrc(id) : '');
@@ -263,10 +305,9 @@
           '<span class="visor__credits" data-visor-credits>' + creditsHtml(n) + '</span></span>' +
         '</div>' +
         mainHtml(main) +
-        '<div class="visor__hints">' + scene.actions.map(function (a, i) { return a.lead ? placeHintHtml(a, i) : ''; }).join('') + acts.slice(1).map(hintHtml).join('') +
+        '<div class="visor__hints">' + scene.actions.map(function (a, i) { return a.lead ? placeHintHtml(a, i, keys.place[i]) : ''; }).join('') + acts.slice(1).map(hintHtml).join('') +
           '<button class="visor__hint visor__hint--sheet" type="button" data-visor-sheet aria-expanded="false" aria-controls="visor-sheet">' +
             '<span class="visor__dots" aria-hidden="true"></span>' + keyHtml(SHEET_KEY) + '<span>Actions</span></button>' +
-          '<a class="visor__hint visor__hint--options" href="' + esc(hallHref('/settings')) + '">' + keyHtml('Esc') + '<span>Options</span></a>' +
         '</div>' +
       '</div>';
   }
@@ -280,20 +321,22 @@
       '<p class="visor__progress-words"><span class="sr-only">' + esc(said) + '</span>' +
       '<span aria-hidden="true">' + esc(progress.id) + ' · ' + progress.pct + '%</span></p></div>';
   }
+  // Options lives only in here (the owner, 2026-11-12), on a key of its own: Escape is Close.
   function sheetHtml(id) {
-    var rows = actionsFor(id).map(function (a) {
+    var keys = resolveKeys(id);
+    var rows = keys.actions.map(function (a) {
       return '<li><a class="visor__row" data-visor-act="' + esc(a.id) + '" ' + actionAttrs(a) + '><span>' + esc(a.label) + '</span>' + keyHtml(a.key) + '</a></li>';
     }).join('');
     var place = scene.actions.map(function (a, i) {
-      return '<li><button class="visor__row" type="button" data-visor-scene="' + i + '"><span>' + esc(a.label) + '</span>' + (a.key ? keyHtml(a.key) : '') + '</button></li>';
-    }).concat(scene.keys.map(function (k) {
-      return '<li><span class="visor__row visor__row--hint"><span>' + esc(k.label) + '</span>' + keyHtml(k.key) + '</span></li>';
+      return '<li><button class="visor__row" type="button" data-visor-scene="' + i + '"><span>' + esc(a.label) + '</span>' + keyHtml(keys.place[i]) + '</button></li>';
+    }).concat(scene.keys.map(function (k, i) {
+      return '<li><span class="visor__row visor__row--hint"><span>' + esc(k.label) + '</span>' + keyHtml(keys.lines[i]) + '</span></li>';
     })).join('');
     return '<div class="visor__sheet-head"><h2 class="visor__sheet-title" id="visor-sheet-title">Actions</h2>' +
-        '<button class="visor__close" type="button" data-visor-close aria-label="Close actions">' + keyHtml('Esc') + '</button></div>' +
+        '<button class="visor__close" type="button" data-visor-close aria-label="Close actions">' + keyHtml(CLOSE_KEY) + '</button></div>' +
       '<p class="visor__cap">' + esc(NAMES[id]) + '</p><ul class="visor__rows">' + rows + '</ul>' +
       (place ? '<p class="visor__cap">This place</p><ul class="visor__rows">' + place + '</ul>' : '') +
-      '<ul class="visor__rows"><li><a class="visor__row" href="' + esc(hallHref('/settings')) + '"><span>Options</span>' + keyHtml('Esc') + '</a></li></ul>';
+      '<ul class="visor__rows"><li><a class="visor__row" data-visor-act="options" href="' + esc(hallHref(keys.options.href)) + '"><span>' + esc(keys.options.label) + '</span>' + keyHtml(keys.options.key) + '</a></li></ul>';
   }
   function shown() { return !!(root && !root.hidden); }
   function render() {
@@ -375,10 +418,12 @@
       if (C && typeof C.openTool === 'function') C.openTool(a.tool);
       return;
     }
+    // Options opens the game's options window over the place when it can (shell-game.js)
+    if (a.id === OPTIONS.id && window.OTBOptionsOverlay && typeof window.OTBOptionsOverlay.open === 'function') { window.OTBOptionsOverlay.open(); return; }
     if (a.href) window.location.assign(hallHref(a.href));
   }
   function find(id) {
-    var acts = actionsFor(character());
+    var acts = resolveKeys(character()).actions;
     for (var i = 0; i < acts.length; i++) if (acts[i].id === id) return acts[i];
     return null;
   }
@@ -415,11 +460,12 @@
     if (!e || e.defaultPrevented || e.ctrlKey || e.metaKey || e.altKey || typeof e.key !== 'string' || e.key.length !== 1) return null;
     var k = e.key.toLowerCase();
     if (k === SHEET_KEY) return 'sheet';
-    var acts = actionsFor(id);
-    for (var i = 0; i < acts.length; i++) if (acts[i].key === k) return acts[i];
-    // then the keys the visor binds for the place (task 1005209); the character's win a clash
+    // the resolver gave each key one owner, so the first match is the only one
+    var keys = resolveKeys(id);
+    for (var i = 0; i < keys.actions.length; i++) if (keys.actions[i].key === k) return keys.actions[i];
     var own = scene ? scene.actions : [];
-    for (var j = 0; j < own.length; j++) if (own[j].bind && own[j].key === k) return own[j];
+    for (var j = 0; j < own.length; j++) if (own[j].bind && keys.place[j] === k) return own[j];
+    if (keys.options.key === k) return keys.options;
     return null;
   }
   // Bubble, on window: a scene or pop-up that used the key has called preventDefault by now.
@@ -460,6 +506,7 @@
     ACTIONS: ACTIONS,
     actionsFor: actionsFor,
     keyFor: keyFor,
+    resolveKeys: resolveKeys,
     creditsText: creditsText,
     character: character,
     pickVersion: pickVersion,

package/modules/hall-ui/records/visor.md

@@ -6,6 +6,13 @@ Covers: `visor.js` + `visor.css`, loaded on Home, `/city`, `/goal-map` and `/thi
 
 The visor is the control and the scene is the view: every main call to action in game mode is on the glass (the accent button, the key hints, the Actions sheet), and a scene carries none of its own. A scene that has something to do registers it with `OTBVisor.scene({ actions, keys })`. ADR 0403 §3 lists the scenes that do not keep it yet; the Governor City keeps it since task 1005209 the sky since task 1005210, and Home's gallery since task 1005211 (below).
 
+## One owner per key (task 1005248, owner 2026-11-12)
+
+- **The bug.** The Artist saw Esc twice: "Options" on the glass, then in the Actions sheet both Close and the Options row said Esc.
+- **The rule.** A key in `ACTIONS` or a scene's registration is a recommendation. `resolveKeys(id)` in `visor.js` hands every key out once, and the glass, the sheet and `keyFor` all read it; nothing else names a key. Who keeps a key, in order: the visor's own (A Actions, Escape Close); the keys a scene binds itself (an action without `bind`, the `keys` lines), because the visor cannot move a key it does not bind, so a second claim on one shows no key; the character's actions; the scene's `bind` actions; Options. A later claimant moves to the next free letter of its own name, then of the alphabet, never onto a key a scene binds on its page (`AVOID`: L 0 / ? F K + - =); with none free it has no key.
+- **Options is only in the sheet** (the owner likes it there), on O, or its next free letter (the Patron's O is the Board room, so P). Pressing it opens the options window over the place, like a click. Escape on the glass is the sheet's Close only. The shell's "last Escape opens the options menu" (`shell-game.js`, ADR 0399 §2.4) is not a visor key and is unchanged.
+- **Tests:** `tests/hall_visor.mjs` proves no shared key for every character over the sky, the city and Home, and over a hostile scene that claims A, Escape, a character key and one key twice.
+
 ## A place's own buttons on the glass (task 1005209, the Governor City first)
 
 - **The scene contract grew two flags.** A scene action's `key` is still a key the scene binds itself, shown beside it in the sheet. With `bind: true` the visor binds that key instead, after the character's keys (a clash goes to the character), for a scene button that had no key of its own. With `lead: true` the action is also the first quiet key hint on the glass (`.visor__hint--place`). Every scene action is still a row under "This place" in the sheet.

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.25.1",
+  "version": "1.25.2",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.25.1",
+      "version": "1.25.2",
       "license": "AGPL-3.0-or-later",
       "dependencies": {
         "express": "^4.21.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.25.1",
+  "version": "1.25.2",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",

package/release-notes.json

@@ -11700,5 +11700,11 @@
       "id": "1005040",
       "text": "Added the Stripe Connect test-mode payment adapter (economy.processor port). Every payout, cash-out, balance and ledger-check call now has a processor to talk to once a test key is set; nothing is live."
     }
+  ],
+  "1.25.2": [
+    {
+      "id": "1005248",
+      "text": "In game mode, no two buttons on the visor share a hotkey any more, and Options now sits only inside the Actions menu with its own key."
+    }
   ]
 }

package/src/module-api.js

@@ -81,7 +81,7 @@ const { sleep } = require('./sleep');
 // MAJOR (see allowBoxScope below): passes the request through untouched.
 function deprecatedNoopMiddleware(_req, _res, next) { next(); }
 
-const CORE_VERSION = '1.25.1'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.25.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');

package/tests/hall_visor.mjs

@@ -77,6 +77,64 @@ test("a place's own key: the visor binds it only when the scene asks, and the ch
   assert.equal(V.keyFor('artisan', ev('c')).id, 'claim', "the character's key wins a clash");
 });
 
+// task 1005248 (owner, 2026-11-12): a key the visor shows is a recommendation, and no two
+// things on the glass or in the sheet ever share one. Every key comes from resolveKeys.
+function shownKeys(r) {
+  const out = [['a', 'Actions'], ['esc', 'Close']];
+  r.actions.forEach((a) => out.push([a.key, a.id]));
+  r.place.forEach((k, i) => out.push([k, 'place ' + i]));
+  r.lines.forEach((k, i) => out.push([k, 'line ' + i]));
+  out.push([r.options.key, 'options']);
+  return out.filter(([k]) => k);
+}
+function assertNoClash(V, who) {
+  for (const c of ['artisan', 'artist', 'patron']) {
+    const keys = shownKeys(V.resolveKeys(c)).map(([k]) => k);
+    assert.equal(new Set(keys).size, keys.length, `${who} / ${c}: one owner per key (${keys.join(' ')})`);
+  }
+}
+const SKY = { name: 'sky', place: '', actions: [{ label: 'Write a thought', key: '/', lead: true, run() {} }, { label: 'Jump to a goal or a thought', key: 'j', bind: true, run() {} }, { label: 'List', key: 'L', run() {} }, { label: 'Tour', key: '?', run() {} }, { label: 'Fit', key: '0', run() {} }, { label: 'Clock · off', key: '', run() {} }], keys: [{ label: 'Look around', key: 'drag' }, { label: 'Zoom', key: '+ −' }] };
+const CITY = { name: 'city', place: 'Governor city', actions: [{ label: 'decide 37 in a row', key: 'd', bind: true, lead: true, run() {} }, { label: 'Archived: Street', run() {} }], keys: [{ label: 'On a card: answer', key: '1–9' }, { label: 'On a card: next', key: '← →' }] };
+
+test('no key ever means two things: every character over every real scene, and Options never on Escape', () => {
+  const V = loadPure();
+  assertNoClash(V, 'no scene');
+  for (const sc of [SKY, CITY, { name: 'home', place: 'Home' }]) { V.scene(sc); assertNoClash(V, sc.name); }
+  for (const c of ['artisan', 'artist', 'patron']) {
+    const r = V.resolveKeys(c);
+    assert.notEqual(r.options.key, 'esc', `${c}: Options is not on Escape; Escape is Close`);
+    assert.ok(r.options.key, `${c}: Options has a key of its own`);
+  }
+  assert.equal(V.resolveKeys('artist').options.key, 'o', 'O is Options where nothing else holds it');
+  assert.equal(V.resolveKeys('patron').options.key, 'p', "the Patron's O is the Board room, so Options moves to its next letter");
+});
+
+test('a clash moves the later claimant to a free letter of its own name, and its key follows', () => {
+  const V = loadPure();
+  const ev = (key) => ({ key, defaultPrevented: false, ctrlKey: false, metaKey: false, altKey: false });
+  const run = () => {};
+  // the worst a scene can register: its own keys on A, Escape, a character key, and twice on one key
+  V.scene({ name: 'x', place: 'X', actions: [
+    { label: 'Grab', key: 'a', run }, { label: 'Exit', key: 'Esc', run }, { label: 'Go', key: 'g', run }, { label: 'Again', key: 'g', run },
+    { label: 'Claim here', key: 'c', bind: true, run }, { label: 'Thing', key: 't', bind: true, run }, { label: 'Open', key: 'o', bind: true, run },
+  ], keys: [{ label: 'Same as Go', key: 'G' }] });
+  assertNoClash(V, 'hostile scene');
+  const r = V.resolveKeys('artisan');
+  const plain = (x) => JSON.parse(JSON.stringify(x));
+  assert.deepEqual(plain(r.place.slice(0, 4)), ['', '', 'g', ''], "A and Escape are the visor's; the scene keeps G once, and a second claim shows no key");
+  assert.equal(r.lines[0], '', 'a key line on a taken key shows no key');
+  assert.equal(r.actions.find((a) => a.id === 'sky').key, 'o', 'Goal sky lost G to the scene, so it moves to the next letter of its name, O');
+  assert.equal(V.keyFor('artisan', ev('o')).id, 'sky', 'and O runs it');
+  assert.equal(V.keyFor('artisan', ev('g')), null, "G is the scene's own now, so the visor does not take it");
+  assert.ok(!['c', 'l', 'a'].includes(r.place[4]), 'Claim here: C is taken, L and A are never handed out');
+  assert.equal(V.keyFor('artisan', ev(r.place[4])).label, 'Claim here');
+  assert.equal(V.keyFor('artisan', ev('c')).id, 'claim', "the character's key still wins");
+  assert.ok(r.place[6] && r.place[6] !== 'o', "Open asked for O after Goal sky took it, so it moves");
+  assert.equal(V.keyFor('artisan', ev(r.place[6])).label, 'Open');
+  assert.equal(V.keyFor('artisan', ev(r.options.key)).id, 'options', 'and Options takes the next free letter');
+  assert.equal(V.keyFor('artisan', ev('Escape')), null, 'the ambient glass never takes Escape');
+});
+
 // task 1005203: the four segments are the version the project is building, in quarters.
 test('progress: the starred version while open, else the one building, else none', () => {
   const V = loadPure();
@@ -238,7 +296,8 @@ test('in game mode the glass shows the place, the main action, the key hints, th
   assert.equal(g.credits, '56,021 credits');
   assert.deepEqual([g.num, g.unit], ['56,021', 'credits'], 'the count and its word are two spans of the same text');
   // task 1005195: every other control is a quiet key hint. Actions kept its key and its sheet; nothing was dropped.
-  assert.deepEqual(g.hints, ['TYour thinking', 'AActions', 'EscOptions']);
+  // task 1005248: Options is only in the sheet, so Escape is on the glass nowhere.
+  assert.deepEqual(g.hints, ['TYour thinking', 'AActions']);
   assert.equal(g.arcs, 2, 'two arcs frame the glass');
   assert.equal(g.sprite, '/builders/characters/artisan-visor.png', 'your picture on the glass is you wearing the visor (task 1005218)');
   assert.deepEqual(errors, []);
@@ -295,7 +354,7 @@ test('a lead scene action is the first key hint, and its click and its key run i
   const { ctx, page, errors } = await open();
   await page.evaluate(() => OTBVisor.scene({ name: 'test', place: 'Test city', actions: [{ label: 'Decide 2 in a row', key: 'd', bind: true, lead: true, run() { window.decided = (window.decided || 0) + 1; } }] }));
   const hints = await page.$$eval('.visor__hints .visor__hint', (h) => h.map((x) => x.textContent));
-  assert.deepEqual(hints, ['DDecide 2 in a row', 'TYour thinking', 'AActions', 'EscOptions']);
+  assert.deepEqual(hints, ['DDecide 2 in a row', 'TYour thinking', 'AActions']);
   await page.click('.visor__hint--place');
   await page.keyboard.press('d');
   assert.equal(await page.evaluate(() => window.decided), 2, 'the hint and D both press it');
@@ -311,7 +370,8 @@ test('the sheet lists the character\'s actions, then this place, and runs a scen
   await page.click('[data-visor-sheet]');
   const rows = await page.$$eval('.visor__sheet .visor__row', (r) => r.map((x) => [...x.children].map((c) => c.textContent).join(' ')));
   // task 1005200: Claim a task and Blockers open classic pages, so they are off the glass.
-  assert.deepEqual(rows, ['Goal sky G', 'Your thinking T', 'Back to centre 0', 'Look around drag', 'Options Esc']);
+  assert.deepEqual(rows, ['Goal sky G', 'Your thinking T', 'Back to centre 0', 'Look around drag', 'Options O']);
+  assert.equal(await page.$eval('.visor__sheet [data-visor-close]', (b) => b.textContent), 'Esc', 'Escape is the Close of the sheet, and only that');
   await page.click('[data-visor-scene="0"]');
   assert.deepEqual(await page.evaluate(() => ({ centred: window.centred, open: OTBVisor.isOpen() })), { centred: true, open: false });
   await ctx.close();