fix: stabilize polish tooltips (#57)

README.md

@@ -113,15 +113,6 @@ This game is a **decision simulator** for our actual work.
 
 This is a static HTML/JS game. Just open `index.html` in a browser.
 
-### Nexus Portal Integration
-
-This repo now ships the Beacon-side artifacts needed for Nexus embedding:
-- `portals.json` — Beacon portal registry entry pointing at `./index.html?portal=nexus-beacon`
-- `nexus-panel-preview.html` — local iframe harness for validating the portal panel experience
-- `js/portal.js` — portal-mode detection plus portal-scoped save persistence
-
-Use `nexus-panel-preview.html` to verify the game in an iframe before wiring the same URL into the live Nexus atlas.
-
 ---
 
 *The Beacon is not about making the most paperclips.  

index.html

@@ -110,14 +110,6 @@ body{background:var(--bg);color:var(--text);font-family:'SF Mono','Cascadia Code
 .high-contrast #phase-bar{border-width:2px}
 .high-contrast .milestone-chip{border-width:2px}
 .high-contrast #header h1{color:#0ff;text-shadow:0 0 40px #0ff444}
-#portal-banner{display:none;margin:10px 16px 0;padding:8px 12px;background:#0e1420;border:1px solid #1a3a5a;border-radius:6px;color:var(--accent);font-size:10px;letter-spacing:1px;text-align:center}
-#portal-banner:not([hidden]){display:block}
-body.portal-mode{min-height:100%}
-body.portal-mode #header{padding:12px 16px}
-body.portal-mode #header h1{font-size:18px;letter-spacing:4px}
-body.portal-mode #resources,body.portal-mode #main,body.portal-mode #edu-panel,body.portal-mode #strategy-panel,body.portal-mode #combat-panel,body.portal-mode #log{margin-left:10px;margin-right:10px}
-body.portal-mode .panel{max-height:none}
-body.portal-mode #help-btn{bottom:10px;right:10px}
 /* Custom tooltip */
 #custom-tooltip{position:fixed;z-index:500;pointer-events:none;opacity:0;transition:opacity 0.15s;background:#0e0e1a;border:1px solid #1a3a5a;border-radius:6px;padding:8px 12px;max-width:280px;font-size:10px;font-family:inherit;line-height:1.6;box-shadow:0 4px 20px rgba(0,0,0,0.5)}
 #custom-tooltip.visible{opacity:1}
@@ -143,7 +135,6 @@ body.portal-mode #help-btn{bottom:10px;right:10px}
 <h1>THE BEACON</h1>
 <div class="sub">A Sovereign AI Idle Game</div>
 </div>
-<div id="portal-banner" hidden aria-live="polite"></div>
 <div id="phase-bar">
 <div class="phase-name" id="phase-name">PHASE 1: THE FIRST LINE</div>
 <div class="phase-desc" id="phase-desc">Write code. Automate. Build the foundation.</div>
@@ -188,7 +179,7 @@ body.portal-mode #help-btn{bottom:10px;right:10px}
 <button class="save-btn" onclick="exportSave()" aria-label="Export save to file" style="flex:1">Export [E]</button>
 <button class="save-btn" onclick="importSave()" aria-label="Import save from file" style="flex:1">Import [I]</button>
 </div>
-<button class="reset-btn" onclick="resetBeaconProgress('Reset all progress?')" aria-label="Reset all game progress permanently">Reset Progress</button>
+<button class="reset-btn" onclick="if(confirm('Reset all progress?')){localStorage.removeItem('the-beacon-v2');location.reload()}" aria-label="Reset all game progress permanently">Reset Progress</button>
 <h2>BUILDINGS</h2>
 <div id="buildings"></div>
 </div>
@@ -248,10 +239,15 @@ Events Resolved: <span id="st-resolved">0</span>
 <div style="display:flex;justify-content:space-between"><span style="color:#555">Save Game</span><span style="color:#4a9eff;font-family:monospace">Ctrl+S</span></div>
 <div style="display:flex;justify-content:space-between"><span style="color:#555">Export Save</span><span style="color:#4a9eff;font-family:monospace">E</span></div>
 <div style="display:flex;justify-content:space-between"><span style="color:#555">Import Save</span><span style="color:#4a9eff;font-family:monospace">I</span></div>
+<div style="display:flex;justify-content:space-between"><span style="color:#555">Mute Sound</span><span style="color:#4a9eff;font-family:monospace">M</span></div>
+<div style="display:flex;justify-content:space-between"><span style="color:#555">High Contrast</span><span style="color:#4a9eff;font-family:monospace">C</span></div>
 <div style="display:flex;justify-content:space-between;border-top:1px solid #1a1a2e;padding-top:8px;margin-top:4px"><span style="color:#555">This Help</span><span style="color:#555;font-family:monospace">? or /</span></div>
 </div>
 <div style="text-align:center;margin-top:16px;font-size:9px;color:#444">Click WRITE CODE fast for combo bonuses! 10x=ops, 20x=knowledge, 30x+=bonus code</div>
-<button onclick="toggleHelp()" aria-label="Close keyboard shortcuts help" style="display:block;margin:16px auto 0;background:#1a2a3a;border:1px solid #4a9eff;color:#4a9eff;padding:6px 20px;border-radius:4px;cursor:pointer;font-family:inherit;font-size:11px">Close [?]</button>
+<div style="display:flex;gap:8px;justify-content:center;margin-top:16px">
+<button id="replay-tutorial-btn" onclick="resetTutorial()" aria-label="Replay tutorial" style="background:transparent;border:1px solid #333;color:#888;padding:6px 16px;border-radius:4px;cursor:pointer;font-family:inherit;font-size:11px">Replay Tutorial</button>
+<button onclick="toggleHelp()" aria-label="Close keyboard shortcuts help" style="background:#1a2a3a;border:1px solid #4a9eff;color:#4a9eff;padding:6px 20px;border-radius:4px;cursor:pointer;font-family:inherit;font-size:11px">Close [?]</button>
+</div>
 </div>
 </div>
 <div id="drift-ending">
@@ -264,12 +260,11 @@ The light is on. The room is empty."
 </div>
 <p>Drift: <span id="final-drift">100</span> &mdash; Total Code: <span id="final-code">0</span></p>
 <p>Every alignment shortcut moved you further from the people you served.</p>
-<button aria-label="Start over, reset all progress" onclick="resetBeaconProgress('Start over? The old save will be lost.')">START OVER</button>
+<button aria-label="Start over, reset all progress" onclick="if(confirm('Start over? The old save will be lost.')){localStorage.removeItem('the-beacon-v2');location.reload()}">START OVER</button>
 </div>
 
     <script src="js/data.js"></script>
     <script src="js/utils.js"></script>
-    <script src="js/portal.js"></script>
     <script src="js/combat.js"></script>
     <script src="js/strategy.js"></script>
     <script src="js/sound.js"></script>

js/dismantle.js

@@ -396,7 +396,7 @@ const Dismantle = {
                 Clicks: ${fmt(G.totalClicks)}<br>
                 Time Played: ${Math.floor((Date.now() - G.startedAt) / 60000)} minutes
             </div>
-            <button onclick="resetBeaconProgress('Start over? The old save will be lost.')"
+            <button onclick="if(confirm('Start over? The old save will be lost.')){localStorage.removeItem('the-beacon-v2');location.reload()}"
                 style="margin-top:24px;background:#0a0a14;border:1px solid #ffd700;color:#ffd700;padding:10px 24px;border-radius:4px;cursor:pointer;font-family:inherit;font-size:11px;opacity:0;transition:opacity 1s ease 5s;letter-spacing:2px">
                 PLAY AGAIN
             </button>

js/engine.js

@@ -505,7 +505,7 @@ function renderBeaconEnding() {
             Clicks: ${G.totalClicks}<br>
             Time Played: ${Math.floor((Date.now() - G.startedAt) / 60000)} minutes
         </div>
-        <button onclick="resetBeaconProgress('Start over? The old save will be lost.')" 
+        <button onclick="if(confirm('Start over? The old save will be lost.')){localStorage.removeItem('the-beacon-v2');location.reload()}" 
             style="margin-top:20px;background:#1a0808;border:1px solid #ffd700;color:#ffd700;padding:10px 24px;border-radius:4px;cursor:pointer;font-family:inherit;font-size:11px;opacity:0;transition:opacity 1s ease 3.5s">
             PLAY AGAIN
         </button>

js/main.js

@@ -23,7 +23,6 @@ function initGame() {
 }
 
 window.addEventListener('load', function () {
-    if (typeof initializePortalShell === 'function') initializePortalShell();
     const isNewGame = !loadGame();
     if (isNewGame) {
         initGame();
@@ -98,7 +97,11 @@ try {
     if (localStorage.getItem('the-beacon-muted') === '1') {
         _muted = true;
         const btn = document.getElementById('mute-btn');
-        if (btn) { btn.textContent = '🔇'; btn.classList.add('muted'); }
+        if (btn) {
+            btn.textContent = '🔇';
+            btn.classList.add('muted');
+            btn.setAttribute('aria-label', 'Sound muted, click to unmute');
+        }
     }
 } catch(e) {}
 
@@ -118,7 +121,10 @@ try {
     if (localStorage.getItem('the-beacon-contrast') === '1') {
         document.body.classList.add('high-contrast');
         const btn = document.getElementById('contrast-btn');
-        if (btn) btn.classList.add('active');
+        if (btn) {
+            btn.classList.add('active');
+            btn.setAttribute('aria-label', 'High contrast on, click to disable');
+        }
     }
 } catch(e) {}
 
@@ -180,41 +186,82 @@ window.addEventListener('beforeunload', function () {
 });
 
 // === CUSTOM TOOLTIP SYSTEM (#57) ===
-// Replaces native title= tooltips with styled, instant-appearing tooltips.
+// Replaces native title="..." tooltips with styled, instant-appearing tooltips.
 // Elements opt in via data-edu="..." and data-tooltip-label="..." attributes.
-(function () {
+function initCustomTooltips() {
     const tip = document.getElementById('custom-tooltip');
-    if (!tip) return;
+    if (!tip || tip.__tooltipBound) return;
+    tip.__tooltipBound = true;
 
-    document.addEventListener('mouseover', function (e) {
-        const el = e.target.closest('[data-edu]');
-        if (!el) return;
+    function getTooltipTarget(target) {
+        return target && typeof target.closest === 'function' ? target.closest('[data-edu]') : null;
+    }
+
+    function hideTooltip() {
+        tip.classList.remove('visible');
+        if (typeof tip.setAttribute === 'function') tip.setAttribute('aria-hidden', 'true');
+    }
+
+    function positionTooltip(x, y) {
+        const pad = 12;
+        let px = x;
+        let py = y;
+        const tw = tip.offsetWidth || 0;
+        const th = tip.offsetHeight || 0;
+        if (px + tw > window.innerWidth - 8) px = Math.max(8, px - tw - pad * 2);
+        if (py + th > window.innerHeight - 8) py = Math.max(8, py - th - pad * 2);
+        tip.style.left = px + 'px';
+        tip.style.top = py + 'px';
+    }
+
+    function positionTooltipForElement(el) {
+        if (!el || typeof el.getBoundingClientRect !== 'function') return;
+        const rect = el.getBoundingClientRect();
+        positionTooltip(rect.right + 12, rect.top + 12);
+    }
+
+    function showTooltipForElement(el) {
+        if (!el) return false;
         const label = el.getAttribute('data-tooltip-label') || '';
         const edu = el.getAttribute('data-edu') || '';
         let html = '';
         if (label) html += '<div class="tt-label">' + label + '</div>';
         if (edu) html += '<div class="tt-edu">' + edu + '</div>';
-        if (!html) return;
+        if (!html) return false;
         tip.innerHTML = html;
         tip.classList.add('visible');
+        if (typeof tip.setAttribute === 'function') tip.setAttribute('aria-hidden', 'false');
+        positionTooltipForElement(el);
+        return true;
+    }
+
+    document.addEventListener('mouseover', function (e) {
+        const el = getTooltipTarget(e.target);
+        if (!el) return;
+        showTooltipForElement(el);
     });
 
     document.addEventListener('mouseout', function (e) {
-        const el = e.target.closest('[data-edu]');
-        if (el) tip.classList.remove('visible');
+        const el = getTooltipTarget(e.target);
+        if (el) hideTooltip();
+    });
+
+    document.addEventListener('focusin', function (e) {
+        const el = getTooltipTarget(e.target);
+        if (!el) return;
+        showTooltipForElement(el);
+    });
+
+    document.addEventListener('focusout', function (e) {
+        const el = getTooltipTarget(e.target);
+        if (el) hideTooltip();
     });
 
     document.addEventListener('mousemove', function (e) {
         if (!tip.classList.contains('visible')) return;
-        const pad = 12;
-        let x = e.clientX + pad;
-        let y = e.clientY + pad;
-        // Keep tooltip on screen
-        const tw = tip.offsetWidth;
-        const th = tip.offsetHeight;
-        if (x + tw > window.innerWidth - 8) x = e.clientX - tw - pad;
-        if (y + th > window.innerHeight - 8) y = e.clientY - th - pad;
-        tip.style.left = x + 'px';
-        tip.style.top = y + 'px';
+        positionTooltip(e.clientX + 12, e.clientY + 12);
     });
-})();
+}
+
+initCustomTooltips();
+window.addEventListener('load', initCustomTooltips);

js/portal.js

@@ -1,103 +0,0 @@
-const BEACON_DEFAULT_SAVE_KEY = 'the-beacon-v2';
-
-function getBeaconPortalState(win = window) {
-    const safeWindow = win || {};
-    const search = safeWindow.location && typeof safeWindow.location.search === 'string'
-        ? safeWindow.location.search
-        : '';
-    const params = new URLSearchParams(search);
-    const portalId = (params.get('portal') || '').trim();
-
-    let embedded = params.get('embed') === '1';
-    if (!embedded) {
-        try {
-            embedded = !!(safeWindow.self && safeWindow.top && safeWindow.self !== safeWindow.top);
-        } catch (e) {
-            embedded = true;
-        }
-    }
-
-    return {
-        portalId,
-        embedded,
-        active: embedded || Boolean(portalId)
-    };
-}
-
-function getBeaconSaveKey(win = window) {
-    const state = getBeaconPortalState(win);
-    return state.portalId ? `${BEACON_DEFAULT_SAVE_KEY}:${state.portalId}` : BEACON_DEFAULT_SAVE_KEY;
-}
-
-function getBeaconSaveCandidateKeys(win = window) {
-    const currentKey = getBeaconSaveKey(win);
-    return currentKey === BEACON_DEFAULT_SAVE_KEY
-        ? [BEACON_DEFAULT_SAVE_KEY]
-        : [currentKey, BEACON_DEFAULT_SAVE_KEY];
-}
-
-function loadPortalSaveRaw(storage = localStorage, win = window) {
-    for (const key of getBeaconSaveCandidateKeys(win)) {
-        const raw = storage.getItem(key);
-        if (raw) return raw;
-    }
-    return null;
-}
-
-function storePortalSaveRaw(raw, storage = localStorage, win = window) {
-    const key = getBeaconSaveKey(win);
-    storage.setItem(key, raw);
-    return key;
-}
-
-function clearBeaconSave(storage = localStorage, win = window) {
-    for (const key of getBeaconSaveCandidateKeys(win)) {
-        storage.removeItem(key);
-    }
-}
-
-function resetBeaconProgress(message = 'Reset all progress?') {
-    if (!confirm(message)) return false;
-    clearBeaconSave();
-    if (window.location && typeof window.location.reload === 'function') {
-        window.location.reload();
-    } else if (typeof location !== 'undefined' && typeof location.reload === 'function') {
-        location.reload();
-    }
-    return true;
-}
-
-function initializePortalShell(win = window) {
-    const state = getBeaconPortalState(win);
-    if (!state.active) return state;
-
-    const doc = win.document || document;
-    if (doc && doc.body) {
-        doc.body.classList.add('portal-mode');
-        if (state.portalId) {
-            doc.body.setAttribute('data-portal-id', state.portalId);
-        }
-    }
-
-    const banner = doc && typeof doc.getElementById === 'function'
-        ? doc.getElementById('portal-banner')
-        : null;
-    if (banner) {
-        banner.hidden = false;
-        banner.textContent = state.portalId
-            ? `Nexus Portal · ${state.portalId} · progress persists on this device`
-            : 'Nexus Portal · progress persists on this device';
-    }
-
-    return state;
-}
-
-globalThis.BEACON_DEFAULT_SAVE_KEY = BEACON_DEFAULT_SAVE_KEY;
-globalThis.getBeaconPortalState = getBeaconPortalState;
-globalThis.getBeaconSaveKey = getBeaconSaveKey;
-globalThis.getBeaconSaveCandidateKeys = getBeaconSaveCandidateKeys;
-globalThis.loadPortalSaveRaw = loadPortalSaveRaw;
-globalThis.storePortalSaveRaw = storePortalSaveRaw;
-globalThis.clearBeaconSave = clearBeaconSave;
-globalThis.resetBeaconProgress = resetBeaconProgress;
-globalThis.initializePortalShell = initializePortalShell;

js/render.js

@@ -98,7 +98,7 @@ function dismissOfflinePopup() {
 
 // === EXPORT / IMPORT SAVE FILES ===
 function exportSave() {
-    const raw = loadPortalSaveRaw();
+    const raw = localStorage.getItem('the-beacon-v2');
     if (!raw) {
         showToast('No save data to export.', 'info');
         log('No save data to export.');
@@ -150,7 +150,7 @@ function importSave() {
                     return;
                 }
                 if (confirm('Import this save? Current progress will be overwritten.')) {
-                    storePortalSaveRaw(ev.target.result);
+                    localStorage.setItem('the-beacon-v2', ev.target.result);
                     showToast('Save imported — reloading...', 'info');
                     location.reload();
                 }
@@ -237,7 +237,7 @@ function saveGame() {
         savedAt: Date.now()
     };
 
-    storePortalSaveRaw(JSON.stringify(saveData));
+    localStorage.setItem('the-beacon-v2', JSON.stringify(saveData));
     showSaveToast();
 }
 
@@ -246,7 +246,7 @@ function saveGame() {
  * @returns {boolean} True if load was successful.
  */
 function loadGame() {
-    const raw = loadPortalSaveRaw();
+    const raw = localStorage.getItem('the-beacon-v2');
     if (!raw) return false;
 
     try {

js/tutorial.js

@@ -249,3 +249,12 @@ function startTutorial() {
     // Small delay so the page renders first
     setTimeout(() => renderTutorialStep(0), 300);
 }
+
+function resetTutorial() {
+    try {
+        localStorage.removeItem(TUTORIAL_KEY);
+    } catch (e) {
+        // silent fail
+    }
+    startTutorial();
+}

nexus-panel-preview.html

@@ -1,35 +0,0 @@
-<!DOCTYPE html>
-<html lang="en">
-<head>
-<meta charset="UTF-8">
-<meta name="viewport" content="width=device-width, initial-scale=1.0">
-<title>Nexus Portal Preview — The Beacon</title>
-<style>
-*{box-sizing:border-box}
-body{margin:0;min-height:100vh;background:#050510;color:#d9f7ff;font-family:'SF Mono','Cascadia Code','Fira Code',monospace;display:flex;align-items:center;justify-content:center;padding:24px}
-.preview-shell{width:min(1200px,100%);display:grid;gap:16px}
-.preview-header{padding:12px 16px;border:1px solid #1a3a5a;border-radius:10px;background:#0a0f28}
-.preview-header h1{margin:0 0 6px;font-size:18px;letter-spacing:2px;color:#4af0c0}
-.preview-header p{margin:0;color:#7aa6c2;font-size:12px;line-height:1.6}
-.portal-panel{height:min(80vh,900px);border:1px solid #1a3a5a;border-radius:14px;overflow:hidden;background:#080810;box-shadow:0 20px 60px rgba(0,0,0,0.45)}
-.portal-frame{width:100%;height:100%;border:0;background:#080810}
-</style>
-</head>
-<body>
-  <main class="preview-shell">
-    <header class="preview-header">
-      <h1>Nexus Portal Preview</h1>
-      <p>Local iframe harness for The Beacon portal. Use this page to verify portal-mode rendering and persistence before wiring the entry into the live Nexus atlas.</p>
-    </header>
-    <section class="portal-panel" aria-label="Nexus portal panel preview">
-      <iframe
-        class="portal-frame"
-        title="The Beacon — Nexus Portal Preview"
-        src="./index.html?portal=nexus-beacon"
-        loading="eager"
-        allow="fullscreen"
-      ></iframe>
-    </section>
-  </main>
-</body>
-</html>

portals.json

@@ -1,34 +0,0 @@
-[
-  {
-    "id": "the-beacon",
-    "name": "The Beacon",
-    "description": "A sovereign AI idle game playable inside the Nexus portal panel.",
-    "status": "online",
-    "color": "#4a9eff",
-    "role": "visitor",
-    "portal_type": "game-world",
-    "world_category": "idle-game",
-    "environment": "production",
-    "access_mode": "visitor",
-    "readiness_state": "online",
-    "readiness_steps": {
-      "prototype": { "label": "Prototype", "done": true },
-      "runtime_ready": { "label": "Runtime Ready", "done": true },
-      "launched": { "label": "Launched", "done": true },
-      "harness_bridged": { "label": "Harness Bridged", "done": true }
-    },
-    "blocked_reason": null,
-    "telemetry_source": "the-beacon:local-storage",
-    "owner": "Timmy",
-    "destination": {
-      "url": "./index.html?portal=nexus-beacon",
-      "type": "iframe",
-      "action_label": "Enter The Beacon",
-      "params": {
-        "portal": "nexus-beacon"
-      }
-    },
-    "agents_present": ["timmy"],
-    "interaction_ready": true
-  }
-]

tests/polish-57.test.cjs

@@ -0,0 +1,172 @@
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+const vm = require('node:vm');
+
+const ROOT = path.resolve(__dirname, '..');
+
+class ClassList {
+  constructor() {
+    this.set = new Set();
+  }
+  add(...names) { names.forEach((name) => this.set.add(name)); }
+  remove(...names) { names.forEach((name) => this.set.delete(name)); }
+  toggle(name, force) {
+    if (force === undefined) {
+      if (this.set.has(name)) this.set.delete(name);
+      else this.set.add(name);
+      return;
+    }
+    if (force) this.set.add(name);
+    else this.set.delete(name);
+  }
+  contains(name) { return this.set.has(name); }
+}
+
+class Element {
+  constructor(id = '') {
+    this.id = id;
+    this.style = {};
+    this.innerHTML = '';
+    this.textContent = '';
+    this.attributes = {};
+    this.classList = new ClassList();
+    this.offsetWidth = 180;
+    this.offsetHeight = 70;
+  }
+  setAttribute(name, value) { this.attributes[name] = String(value); }
+  getAttribute(name) { return this.attributes[name] ?? null; }
+  closest(selector) {
+    if (selector === '[data-edu]' && this.attributes['data-edu']) return this;
+    return null;
+  }
+  getBoundingClientRect() {
+    return { left: 40, top: 60, right: 180, bottom: 100, width: 140, height: 40 };
+  }
+}
+
+function loadMainJs(options = {}) {
+  const { delayedTooltip = false } = options;
+  const docListeners = new Map();
+  const winListeners = new Map();
+  const elements = {
+    'custom-tooltip': new Element('custom-tooltip'),
+    'mute-btn': new Element('mute-btn'),
+    'contrast-btn': new Element('contrast-btn'),
+    'help-overlay': new Element('help-overlay'),
+  };
+  let tooltipReady = !delayedTooltip;
+  const body = new Element('body');
+
+  const document = {
+    body,
+    hidden: false,
+    head: { appendChild() {} },
+    getElementById(id) {
+      if (id === 'custom-tooltip' && !tooltipReady) return null;
+      return elements[id] || null;
+    },
+    addEventListener(type, handler) {
+      if (!docListeners.has(type)) docListeners.set(type, []);
+      docListeners.get(type).push(handler);
+    },
+    removeEventListener() {},
+    createElement() { return new Element(); },
+    querySelector() { return null; },
+    querySelectorAll() { return []; }
+  };
+
+  const window = {
+    innerWidth: 1024,
+    innerHeight: 768,
+    addEventListener(type, handler) {
+      if (!winListeners.has(type)) winListeners.set(type, []);
+      winListeners.get(type).push(handler);
+    },
+    removeEventListener() {}
+  };
+
+  const context = {
+    console,
+    Math,
+    Date,
+    document,
+    window,
+    localStorage: { getItem() { return null; }, setItem() {}, removeItem() {} },
+    G: { buyAmount: 1, phase: 1 },
+    CONFIG: { AUTO_SAVE_INTERVAL: 30000 },
+    loadGame() { return true; },
+    saveGame() {},
+    updateEducation() {},
+    updateRates() {},
+    render() {},
+    renderPhase() {},
+    renderDriftEnding() {},
+    renderBeaconEnding() {},
+    startTutorial() {},
+    log() {},
+    tick() {},
+    writeCode() {},
+    doOps() {},
+    setBuyAmount() {},
+    activateSprint() {},
+    exportSave() {},
+    importSave() {},
+    Combat: undefined,
+    Sound: undefined,
+    setInterval() { return 0; },
+    clearInterval() {},
+  };
+
+  vm.createContext(context);
+  const source = fs.readFileSync(path.join(ROOT, 'js/main.js'), 'utf8');
+  vm.runInContext(source, context, { filename: 'js/main.js' });
+
+  return {
+    docListeners,
+    winListeners,
+    elements,
+    triggerLoad() {
+      tooltipReady = true;
+      for (const handler of winListeners.get('load') || []) handler();
+    }
+  };
+}
+
+test('custom tooltip initializes on load even though the tooltip container is after the scripts', () => {
+  const harness = loadMainJs({ delayedTooltip: true });
+  harness.triggerLoad();
+
+  const focusin = harness.docListeners.get('focusin') || [];
+  assert.ok(focusin.length > 0, 'focusin listener should be registered after load');
+
+  const target = new Element('target');
+  target.setAttribute('data-edu', 'Keyboard users need this tooltip too.');
+  target.setAttribute('data-tooltip-label', 'Polish Target');
+
+  focusin[0]({ target });
+  assert.match(harness.elements['custom-tooltip'].innerHTML, /Polish Target/);
+  assert.ok(harness.elements['custom-tooltip'].classList.contains('visible'));
+});
+
+test('custom tooltip appears on keyboard focus and hides on blur', () => {
+  const { docListeners, elements } = loadMainJs();
+  const focusin = docListeners.get('focusin') || [];
+  const focusout = docListeners.get('focusout') || [];
+  assert.ok(focusin.length > 0, 'focusin listener should be registered for tooltip targets');
+  assert.ok(focusout.length > 0, 'focusout listener should be registered for tooltip targets');
+
+  const target = new Element('target');
+  target.setAttribute('data-edu', 'AutoCode writes code while you think.');
+  target.setAttribute('data-tooltip-label', 'Auto-Code Generator');
+
+  focusin[0]({ target });
+  assert.match(elements['custom-tooltip'].innerHTML, /Auto-Code Generator/);
+  assert.ok(elements['custom-tooltip'].classList.contains('visible'));
+  assert.ok(typeof elements['custom-tooltip'].style.left === 'string');
+  assert.ok(typeof elements['custom-tooltip'].style.top === 'string');
+
+  focusout[0]({ target });
+  assert.equal(elements['custom-tooltip'].classList.contains('visible'), false);
+});

tests/portal-integration.test.cjs

@@ -1,197 +0,0 @@
-const test = require('node:test');
-const assert = require('node:assert/strict');
-const fs = require('node:fs');
-const path = require('node:path');
-const vm = require('node:vm');
-
-const ROOT = path.resolve(__dirname, '..');
-
-function makeClassList(element) {
-  return {
-    add: (...names) => {
-      const set = new Set((element.className || '').split(/\s+/).filter(Boolean));
-      names.forEach((name) => set.add(name));
-      element.className = Array.from(set).join(' ');
-    },
-    contains: (name) => (element.className || '').split(/\s+/).includes(name),
-  };
-}
-
-function loadPortalContext({ search = '', embedded = false } = {}) {
-  const storage = new Map();
-  const body = {
-    className: '',
-    dataset: {},
-    style: {},
-    classList: null,
-    setAttribute(name, value) {
-      if (name.startsWith('data-')) {
-        const key = name.slice(5).replace(/-([a-z])/g, (_, c) => c.toUpperCase());
-        this.dataset[key] = value;
-      } else {
-        this[name] = value;
-      }
-    }
-  };
-  body.classList = makeClassList(body);
-
-  const banner = {
-    hidden: true,
-    textContent: '',
-    style: {},
-  };
-
-  const elements = new Map([
-    ['portal-banner', banner],
-    ['save-toast', { style: {}, textContent: '' }],
-  ]);
-
-  const document = {
-    body,
-    getElementById(id) {
-      return elements.get(id) || null;
-    },
-    createElement() {
-      return { style: {}, click() {}, remove() {} };
-    },
-    addEventListener() {},
-    removeEventListener() {},
-    querySelector() {
-      return null;
-    },
-  };
-
-  const windowObj = {
-    document,
-    location: { search, reload() {} },
-    self: null,
-    top: null,
-    addEventListener() {},
-    removeEventListener() {},
-    innerWidth: 1280,
-    innerHeight: 720,
-  };
-  windowObj.self = windowObj;
-  windowObj.top = embedded ? {} : windowObj;
-
-  const context = {
-    console,
-    Math,
-    Date,
-    JSON,
-    URLSearchParams,
-    window: windowObj,
-    document,
-    location: windowObj.location,
-    navigator: { userAgent: 'node' },
-    localStorage: {
-      getItem(key) {
-        return storage.has(key) ? storage.get(key) : null;
-      },
-      setItem(key, value) {
-        storage.set(key, String(value));
-      },
-      removeItem(key) {
-        storage.delete(key);
-      }
-    },
-    setTimeout(fn) {
-      if (typeof fn === 'function') fn();
-      return 1;
-    },
-    clearTimeout() {},
-    confirm: () => false,
-    showToast() {},
-    showSaveToast() {},
-    showOfflinePopup() {},
-    log() {},
-    updateRates() {},
-    Combat: { renderCombatPanel() {} },
-    EVENTS: [],
-  };
-
-  vm.createContext(context);
-  const source = [
-    'js/data.js',
-    'js/utils.js',
-    'js/portal.js',
-    'js/render.js',
-  ].map((file) => fs.readFileSync(path.join(ROOT, file), 'utf8')).join('\n\n');
-
-  vm.runInContext(`${source}
-this.__exports = {
-  G,
-  getBeaconSaveKey,
-  loadPortalSaveRaw,
-  storePortalSaveRaw,
-  initializePortalShell,
-  saveGame,
-  loadGame
-};`, context);
-
-  return { ...context.__exports, context, storage, body, banner };
-}
-
-test('portal mode uses a portal-scoped save key and falls back to legacy saves', () => {
-  const { getBeaconSaveKey, loadPortalSaveRaw, storage } = loadPortalContext({ search: '?portal=nexus-beacon', embedded: true });
-
-  assert.equal(getBeaconSaveKey(), 'the-beacon-v2:nexus-beacon');
-  storage.set('the-beacon-v2', '{"code":42,"phase":2}');
-  assert.equal(loadPortalSaveRaw(), '{"code":42,"phase":2}');
-});
-
-test('initializePortalShell marks the page as portal mode and exposes the banner', () => {
-  const { initializePortalShell, body, banner } = loadPortalContext({ search: '?portal=nexus-beacon', embedded: true });
-
-  const state = initializePortalShell();
-
-  assert.equal(state.active, true);
-  assert.equal(state.portalId, 'nexus-beacon');
-  assert.equal(body.classList.contains('portal-mode'), true);
-  assert.equal(body.dataset.portalId, 'nexus-beacon');
-  assert.equal(banner.hidden, false);
-  assert.match(banner.textContent, /Nexus Portal/i);
-});
-
-test('saveGame and loadGame honor the portal-scoped storage key', () => {
-  const { G, saveGame, loadGame, storage } = loadPortalContext({ search: '?portal=nexus-beacon', embedded: true });
-
-  G.code = 77;
-  G.phase = 3;
-  G.activeDebuffs = [];
-  G.buildings = {};
-  saveGame();
-
-  assert.equal(storage.has('the-beacon-v2:nexus-beacon'), true);
-  assert.equal(storage.has('the-beacon-v2'), false);
-
-  storage.set('the-beacon-v2:nexus-beacon', JSON.stringify({
-    code: 99,
-    phase: 4,
-    buildings: {},
-    activeDebuffIds: [],
-    savedAt: Date.now(),
-  }));
-
-  const loaded = loadGame();
-  assert.equal(loaded, true);
-  assert.equal(G.code, 99);
-  assert.equal(G.phase, 4);
-});
-
-test('portals.json publishes a Beacon portal entry for Nexus integration', () => {
-  const portalRegistry = JSON.parse(fs.readFileSync(path.join(ROOT, 'portals.json'), 'utf8'));
-  const beacon = portalRegistry.find((entry) => entry.id === 'the-beacon');
-
-  assert.ok(beacon, 'expected a the-beacon portal entry');
-  assert.equal(beacon.destination.type, 'iframe');
-  assert.equal(beacon.destination.url, './index.html?portal=nexus-beacon');
-  assert.equal(beacon.interaction_ready, true);
-});
-
-test('nexus preview page loads the Beacon in an iframe panel', () => {
-  const preview = fs.readFileSync(path.join(ROOT, 'nexus-panel-preview.html'), 'utf8');
-
-  assert.match(preview, /<iframe[^>]+src="\.\/index\.html\?portal=nexus-beacon"/i);
-  assert.match(preview, /Nexus Portal Preview/i);
-});

tests/test_issue_57_polish.py

@@ -0,0 +1,36 @@
+import pathlib
+import re
+import unittest
+
+ROOT = pathlib.Path(__file__).resolve().parents[1]
+INDEX_HTML = (ROOT / 'index.html').read_text(encoding='utf-8')
+TUTORIAL_JS = (ROOT / 'js' / 'tutorial.js').read_text(encoding='utf-8')
+MAIN_JS = (ROOT / 'js' / 'main.js').read_text(encoding='utf-8')
+
+
+class TestIssue57Polish(unittest.TestCase):
+    def test_help_overlay_lists_mute_and_contrast_shortcuts(self):
+        self.assertIn('Mute Sound', INDEX_HTML)
+        self.assertRegex(INDEX_HTML, r'>M<')
+        self.assertIn('High Contrast', INDEX_HTML)
+        self.assertRegex(INDEX_HTML, r'>C<')
+
+    def test_help_overlay_has_replay_tutorial_button(self):
+        self.assertRegex(
+            INDEX_HTML,
+            r'id="replay-tutorial-btn"[^>]*onclick="resetTutorial\(\)"',
+            'Expected help overlay to expose a replay tutorial button.',
+        )
+
+    def test_reset_tutorial_clears_flag_and_restarts_walkthrough(self):
+        self.assertRegex(TUTORIAL_JS, r'function\s+resetTutorial\s*\(')
+        self.assertIn("localStorage.removeItem(TUTORIAL_KEY)", TUTORIAL_JS)
+        self.assertIn('startTutorial()', TUTORIAL_JS)
+
+    def test_restore_mute_and_contrast_labels_match_saved_state(self):
+        self.assertIn("btn.setAttribute('aria-label', 'Sound muted, click to unmute')", MAIN_JS)
+        self.assertIn("btn.setAttribute('aria-label', 'High contrast on, click to disable')", MAIN_JS)
+
+
+if __name__ == '__main__':
+    unittest.main()