fix: stabilize polish tooltips (#57)

Merge PR #143 (squash)

index.html

@@ -239,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">

js/data.js

@@ -165,6 +165,9 @@ const G = {
     dismantleTriggered: false,
     dismantleActive: false,
     dismantleStage: 0,
+    dismantleResourceIndex: 0,
+    dismantleResourceTimer: 0,
+    dismantleDeferUntilAt: 0,
     dismantleComplete: false
 };
 

js/dismantle.js

@@ -14,10 +14,10 @@ const Dismantle = {
     tickTimer: 0,
     active: false,
     triggered: false,
-    deferUntilTick: 0,
+    deferUntilAt: 0,
 
     // Timing: seconds between each dismantle stage
-    STAGE_INTERVALS: [0, 3.0, 2.5, 2.5, 2.0, 3.5, 2.0, 2.0, 2.5],
+    STAGE_INTERVALS: [0, 3.0, 2.5, 2.5, 2.0, 6.3, 2.0, 2.0, 2.5],
 
     // The quantum chips effect: resource items disappear one by one
     // at specific tick marks within a stage (like Paperclips' quantum chips)
@@ -39,7 +39,8 @@ const Dismantle = {
      */
     checkTrigger() {
         if (this.triggered || G.dismantleTriggered || this.active || G.dismantleActive || G.dismantleComplete) return;
-        if ((G.tick || 0) < (this.deferUntilTick || 0)) return;
+        const deferUntilAt = G.dismantleDeferUntilAt || this.deferUntilAt || 0;
+        if (Date.now() < deferUntilAt) return;
         if (!this.isEligible()) return;
         this.offerChoice();
     },
@@ -53,6 +54,9 @@ const Dismantle = {
         G.dismantleActive = false;
         G.dismantleComplete = false;
         G.dismantleStage = 0;
+        G.dismantleResourceIndex = 0;
+        G.dismantleResourceTimer = 0;
+        G.dismantleDeferUntilAt = 0;
         G.beaconEnding = false;
         G.running = true;
 
@@ -105,7 +109,8 @@ const Dismantle = {
         this.clearChoice();
         this.triggered = false;
         G.dismantleTriggered = false;
-        this.deferUntilTick = (G.tick || 0) + 50;
+        this.deferUntilAt = Date.now() + 5000;
+        G.dismantleDeferUntilAt = this.deferUntilAt;
         log('The Beacon waits. It will ask again.');
     },
 
@@ -115,12 +120,14 @@ const Dismantle = {
     begin() {
         this.active = true;
         this.triggered = false;
+        this.deferUntilAt = 0;
         this.stage = 1;
         this.tickTimer = 0;
         G.dismantleTriggered = false;
         G.dismantleActive = true;
         G.dismantleStage = 1;
         G.dismantleComplete = false;
+        G.dismantleDeferUntilAt = 0;
         G.beaconEnding = false;
         G.running = true; // keep tick running for dismantle
 
@@ -135,6 +142,7 @@ const Dismantle = {
         this.resourceSequence = this.getResourceList();
         this.resourceIndex = 0;
         this.resourceTimer = 0;
+        this.syncProgress();
 
         log('', false);
         log('=== THE UNBUILDING ===', true);
@@ -180,6 +188,7 @@ const Dismantle = {
                 this.dismantleNextResource();
                 this.resourceIndex++;
             }
+            this.syncProgress();
         }
 
         // Advance to next stage
@@ -195,6 +204,7 @@ const Dismantle = {
      */
     advanceStage() {
         this.stage++;
+        this.syncProgress();
 
         if (this.stage <= 8) {
             this.renderStage();
@@ -210,6 +220,12 @@ const Dismantle = {
         }
     },
 
+    syncProgress() {
+        G.dismantleStage = this.stage;
+        G.dismantleResourceIndex = this.resourceIndex;
+        G.dismantleResourceTimer = this.resourceTimer;
+    },
+
     /**
      * Disappear the next resource in the sequence.
      */
@@ -445,7 +461,11 @@ const Dismantle = {
             this.active = true;
             this.triggered = false;
             this.stage = G.dismantleStage || 1;
+            this.deferUntilAt = G.dismantleDeferUntilAt || 0;
             G.running = true;
+            this.resourceSequence = this.getResourceList();
+            this.resourceIndex = G.dismantleResourceIndex || 0;
+            this.resourceTimer = G.dismantleResourceTimer || 0;
 
             if (this.stage >= 9) {
                 this.renderFinal();
@@ -461,6 +481,11 @@ const Dismantle = {
             this.triggered = true;
             this.renderChoice();
         }
+
+        // Restore defer cooldown even if not triggered
+        if (G.dismantleDeferUntilAt > 0) {
+            this.deferUntilAt = G.dismantleDeferUntilAt;
+        }
     },
 
     /**
@@ -501,6 +526,10 @@ const Dismantle = {
                 case 8: this.instantHide('log'); break;
             }
         }
+
+        if (this.stage === 5 && this.resourceIndex > 0) {
+            this.instantHideFirstResources(this.resourceIndex);
+        }
     },
 
     instantHide(id) {
@@ -508,6 +537,16 @@ const Dismantle = {
         if (el) el.style.display = 'none';
     },
 
+    instantHideFirstResources(count) {
+        const resources = this.getResourceList().slice(0, count);
+        resources.forEach((r) => {
+            const el = document.getElementById(r.id);
+            if (!el) return;
+            const parent = el.closest('.res');
+            if (parent) parent.style.display = 'none';
+        });
+    },
+
     instantHideActionButtons() {
         const actionPanel = document.getElementById('action-panel');
         if (!actionPanel) return;

js/main.js

@@ -35,7 +35,7 @@ window.addEventListener('load', function () {
         if (G.driftEnding) {
             G.running = false;
             renderDriftEnding();
-        } else if (typeof Dismantle !== 'undefined' && (G.dismantleTriggered || G.dismantleActive || G.dismantleComplete)) {
+        } else if (typeof Dismantle !== 'undefined' && (G.dismantleTriggered || G.dismantleActive || G.dismantleComplete || G.dismantleDeferUntilAt > 0)) {
             Dismantle.restore();
         } else if (G.beaconEnding) {
             G.running = false;
@@ -97,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) {}
 
@@ -117,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) {}
 
@@ -179,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/render.js

@@ -37,6 +37,18 @@ function renderStrategy() {
 function renderAlignment() {
     const container = document.getElementById('alignment-ui');
     if (!container) return;
+
+    if (G.dismantleActive || G.dismantleComplete) {
+        container.innerHTML = '';
+        container.style.display = 'none';
+        return;
+    }
+
+    if (G.dismantleTriggered && !G.dismantleActive && !G.dismantleComplete && typeof Dismantle !== 'undefined' && Dismantle.triggered) {
+        Dismantle.renderChoice();
+        return;
+    }
+
     if (G.pendingAlignment) {
         container.innerHTML = `
             <div style="background:#1a0808;border:1px solid #f44336;padding:10px;border-radius:4px;margin-top:8px">
@@ -218,6 +230,9 @@ function saveGame() {
         dismantleTriggered: G.dismantleTriggered || false,
         dismantleActive: G.dismantleActive || false,
         dismantleStage: G.dismantleStage || 0,
+        dismantleResourceIndex: G.dismantleResourceIndex || 0,
+        dismantleResourceTimer: G.dismantleResourceTimer || 0,
+        dismantleDeferUntilAt: G.dismantleDeferUntilAt || 0,
         dismantleComplete: G.dismantleComplete || false,
         savedAt: Date.now()
     };
@@ -251,7 +266,8 @@ function loadGame() {
             'lastEventAt', 'totalEventsResolved', 'buyAmount',
             'sprintActive', 'sprintTimer', 'sprintCooldown',
             'swarmFlag', 'swarmRate', 'strategicFlag', 'projectsCollapsed',
-            'dismantleTriggered', 'dismantleActive', 'dismantleStage', 'dismantleComplete'
+            'dismantleTriggered', 'dismantleActive', 'dismantleStage',
+            'dismantleResourceIndex', 'dismantleResourceTimer', 'dismantleDeferUntilAt', 'dismantleComplete'
         ];
 
         G.isLoading = true;

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();
+}

tests/dismantle.test.cjs

@@ -209,6 +209,7 @@ this.__exports = {
   G,
   Dismantle,
   tick,
+  renderAlignment: typeof renderAlignment === 'function' ? renderAlignment : null,
   saveGame: typeof saveGame === 'function' ? saveGame : null,
   loadGame: typeof loadGame === 'function' ? loadGame : null
 };`, context);
@@ -242,13 +243,92 @@ test('tick offers the Unbuilding instead of ending the game immediately', () =>
   assert.match(document.getElementById('alignment-ui').innerHTML, /THE UNBUILDING/);
 });
 
+test('renderAlignment does not wipe the Unbuilding prompt after it is offered', () => {
+  const { G, tick, renderAlignment, document } = loadBeacon({ includeRender: true });
+
+  G.totalCode = 1_000_000_000;
+  G.totalRescues = 100_000;
+  G.phase = 6;
+  G.pactFlag = 1;
+  G.harmony = 60;
+  G.beaconEnding = false;
+  G.running = true;
+  G.activeProjects = [];
+  G.completedProjects = [];
+
+  tick();
+  renderAlignment();
+
+  assert.match(document.getElementById('alignment-ui').innerHTML, /THE UNBUILDING/);
+});
+
+test('active Unbuilding suppresses pending alignment event UI', () => {
+  const { G, Dismantle, renderAlignment, document } = loadBeacon({ includeRender: true });
+
+  G.pendingAlignment = true;
+  G.dismantleActive = true;
+  Dismantle.active = true;
+
+  renderAlignment();
+
+  assert.equal(document.getElementById('alignment-ui').innerHTML, '');
+  assert.equal(document.getElementById('alignment-ui').style.display, 'none');
+});
+
+test('stage five lasts long enough to dissolve every resource card', () => {
+  const { G, Dismantle } = loadBeacon();
+
+  Dismantle.begin();
+  Dismantle.stage = 5;
+  Dismantle.tickTimer = 0;
+  Dismantle.resourceSequence = Dismantle.getResourceList();
+  Dismantle.resourceIndex = 0;
+  Dismantle.resourceTimer = 0;
+  G.dismantleActive = true;
+  G.dismantleStage = 5;
+
+  for (let i = 0; i < 63; i++) Dismantle.tick(0.1);
+
+  assert.equal(Dismantle.resourceIndex, Dismantle.resourceSequence.length);
+});
+
+test('save/load restores partial stage-five dissolve progress', () => {
+  const { G, Dismantle, saveGame, loadGame, document } = loadBeacon({ includeRender: true });
+
+  G.startedAt = Date.now();
+  G.dismantleTriggered = true;
+  G.dismantleActive = true;
+  G.dismantleStage = 5;
+  G.dismantleComplete = false;
+  G.dismantleResourceIndex = 4;
+  G.dismantleResourceTimer = 4.05;
+
+  saveGame();
+
+  G.dismantleTriggered = false;
+  G.dismantleActive = false;
+  G.dismantleStage = 0;
+  G.dismantleComplete = false;
+  G.dismantleResourceIndex = 0;
+  G.dismantleResourceTimer = 0;
+  Dismantle.resourceIndex = 0;
+  Dismantle.resourceTimer = 0;
+
+  assert.equal(loadGame(), true);
+  Dismantle.restore();
+
+  assert.equal(Dismantle.resourceIndex, 4);
+  assert.equal(document.getElementById('r-harmony').closest('.res').style.display, 'none');
+  assert.equal(document.getElementById('r-ops').closest('.res').style.display, 'none');
+  assert.notEqual(document.getElementById('r-rescues').closest('.res').style.display, 'none');
+});
+
 test('deferring the Unbuilding clears the prompt and allows it to return later', () => {
   const { G, Dismantle, document } = loadBeacon();
 
   G.totalCode = 1_000_000_000;
   G.phase = 6;
   G.pactFlag = 1;
-  G.tick = 0;
 
   Dismantle.checkTrigger();
   assert.equal(G.dismantleTriggered, true);
@@ -257,15 +337,44 @@ test('deferring the Unbuilding clears the prompt and allows it to return later',
   assert.equal(G.dismantleTriggered, false);
   assert.equal(document.getElementById('alignment-ui').innerHTML, '');
 
-  G.tick = (Dismantle.deferUntilTick || 0) - 0.1;
+  Dismantle.deferUntilAt = Date.now() + 1000;
+  G.dismantleDeferUntilAt = Dismantle.deferUntilAt;
   Dismantle.checkTrigger();
   assert.equal(G.dismantleTriggered, false);
 
-  G.tick = (Dismantle.deferUntilTick || 0) + 1;
+  Dismantle.deferUntilAt = Date.now() - 1;
+  G.dismantleDeferUntilAt = Dismantle.deferUntilAt;
   Dismantle.checkTrigger();
   assert.equal(G.dismantleTriggered, true);
 });
 
+test('defer cooldown survives save and reload', () => {
+  const { G, Dismantle, saveGame, loadGame } = loadBeacon({ includeRender: true });
+
+  G.startedAt = Date.now();
+  G.totalCode = 1_000_000_000;
+  G.phase = 6;
+  G.pactFlag = 1;
+
+  Dismantle.checkTrigger();
+  Dismantle.defer();
+  assert.ok((Dismantle.deferUntilAt || 0) > Date.now());
+
+  saveGame();
+
+  G.dismantleTriggered = false;
+  G.dismantleActive = false;
+  G.dismantleComplete = false;
+  G.dismantleDeferUntilAt = 0;
+  Dismantle.triggered = false;
+  Dismantle.deferUntilAt = 0;
+
+  assert.equal(loadGame(), true);
+  Dismantle.checkTrigger();
+
+  assert.equal(G.dismantleTriggered, false);
+});
+
 test('save and load preserve dismantle progress', () => {
   const { G, saveGame, loadGame } = loadBeacon({ includeRender: true });
 
@@ -300,4 +409,46 @@ test('restore re-renders an offered but not-yet-started Unbuilding prompt', () =
   Dismantle.restore();
 
   assert.match(document.getElementById('alignment-ui').innerHTML, /THE UNBUILDING/);
-});
+});
+
+test('defer cooldown persists after save/load when dismantleTriggered is false', () => {
+  const { G, Dismantle, saveGame, loadGame } = loadBeacon({ includeRender: true });
+
+  G.startedAt = Date.now();
+  G.totalCode = 1_000_000_000;
+  G.phase = 6;
+  G.pactFlag = 1;
+
+  // Trigger the Unbuilding
+  Dismantle.checkTrigger();
+  assert.equal(G.dismantleTriggered, true);
+
+  // Defer it
+  Dismantle.defer();
+  assert.equal(G.dismantleTriggered, false);
+  assert.ok((Dismantle.deferUntilAt || 0) > Date.now());
+  assert.ok((G.dismantleDeferUntilAt || 0) > Date.now());
+
+  // Save the game
+  saveGame();
+
+  // Clear state (simulate reload)
+  G.dismantleTriggered = false;
+  G.dismantleActive = false;
+  G.dismantleComplete = false;
+  G.dismantleDeferUntilAt = 0;
+  Dismantle.triggered = false;
+  Dismantle.deferUntilAt = 0;
+
+  // Load the game
+  assert.equal(loadGame(), true);
+  Dismantle.restore(); // Call restore to restore defer cooldown
+
+  // The cooldown should be restored
+  assert.ok((Dismantle.deferUntilAt || 0) > Date.now(), 'deferUntilAt should be restored');
+  assert.ok((G.dismantleDeferUntilAt || 0) > Date.now(), 'G.dismantleDeferUntilAt should be restored');
+
+  // checkTrigger should not trigger because cooldown is active
+  Dismantle.checkTrigger();
+  assert.equal(G.dismantleTriggered, false, 'dismantleTriggered should remain false during cooldown');
+});

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/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()