fix: stabilize polish tooltips (#57)

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">
@@ -267,7 +272,6 @@ The light is on. The room is empty."
     <script src="js/render.js"></script>
     <script src="js/tutorial.js"></script>
     <script src="js/dismantle.js"></script>
-    <script src="js/compounding-export.js"></script>
     <script src="js/main.js"></script>
   
 

js/compounding-export.js

@@ -1,124 +0,0 @@
-const COMPOUNDING_EXPORT_URL_KEY = 'the-beacon-compounding-export-url';
-const COMPOUNDING_EXPORT_QUEUE_KEY = 'the-beacon-compounding-export-queue';
-
-const CompoundingExport = {
-    lastBoundary: -1,
-
-    getEndpoint() {
-        try {
-            return localStorage.getItem(COMPOUNDING_EXPORT_URL_KEY) || '';
-        } catch (e) {
-            return '';
-        }
-    },
-
-    loadQueue() {
-        try {
-            const raw = localStorage.getItem(COMPOUNDING_EXPORT_QUEUE_KEY);
-            if (!raw) return [];
-            const parsed = JSON.parse(raw);
-            return Array.isArray(parsed) ? parsed : [];
-        } catch (e) {
-            return [];
-        }
-    },
-
-    saveQueue(queue) {
-        try {
-            localStorage.setItem(COMPOUNDING_EXPORT_QUEUE_KEY, JSON.stringify(queue));
-        } catch (e) {
-            // noop
-        }
-    },
-
-    buildSnapshot() {
-        return {
-            source: 'the-beacon',
-            tickBoundary: Math.floor(G.tick || 0),
-            exportedAt: Date.now(),
-            phase: G.phase || 1,
-            trust: G.trust || 0,
-            harmony: G.harmony || 0,
-            resources: {
-                code: G.code || 0,
-                compute: G.compute || 0,
-                knowledge: G.knowledge || 0,
-                users: G.users || 0,
-                impact: G.impact || 0,
-                rescues: G.rescues || 0,
-                ops: G.ops || 0,
-                trust: G.trust || 0,
-                creativity: G.creativity || 0,
-                harmony: G.harmony || 0,
-            },
-            totals: {
-                totalCode: G.totalCode || 0,
-                totalCompute: G.totalCompute || 0,
-                totalKnowledge: G.totalKnowledge || 0,
-                totalUsers: G.totalUsers || 0,
-                totalImpact: G.totalImpact || 0,
-                totalRescues: G.totalRescues || 0,
-            },
-            projects: {
-                active: Array.isArray(G.activeProjects) ? [...G.activeProjects] : [],
-                completed: Array.isArray(G.completedProjects) ? [...G.completedProjects] : [],
-                completedCount: Array.isArray(G.completedProjects) ? G.completedProjects.length : 0,
-            },
-            flags: {
-                deployFlag: G.deployFlag || 0,
-                sovereignFlag: G.sovereignFlag || 0,
-                beaconFlag: G.beaconFlag || 0,
-                pactFlag: G.pactFlag || 0,
-            }
-        };
-    },
-
-    async flush() {
-        const endpoint = this.getEndpoint();
-        const queue = this.loadQueue();
-        if (!endpoint || !queue.length || typeof fetch !== 'function') return false;
-        try {
-            const resp = await fetch(endpoint, {
-                method: 'POST',
-                headers: { 'Content-Type': 'application/json' },
-                body: JSON.stringify({ source: 'the-beacon', snapshots: queue })
-            });
-            if (!resp || !resp.ok) return false;
-            this.saveQueue([]);
-            return true;
-        } catch (e) {
-            return false;
-        }
-    },
-
-    async onTickBoundary() {
-        const boundary = Math.floor(G.tick || 0);
-        if (boundary <= this.lastBoundary) return false;
-        this.lastBoundary = boundary;
-        const queue = this.loadQueue();
-        queue.push(this.buildSnapshot());
-
-        const endpoint = this.getEndpoint();
-        if (!endpoint || typeof fetch !== 'function') {
-            this.saveQueue(queue);
-            return true;
-        }
-
-        this.saveQueue([]);
-        try {
-            const resp = await fetch(endpoint, {
-                method: 'POST',
-                headers: { 'Content-Type': 'application/json' },
-                body: JSON.stringify({ source: 'the-beacon', snapshots: queue })
-            });
-            if (!resp || !resp.ok) {
-                this.saveQueue(queue);
-                return false;
-            }
-            return true;
-        } catch (e) {
-            this.saveQueue(queue);
-            return false;
-        }
-    }
-};

js/engine.js

@@ -246,10 +246,6 @@ function tick() {
         renderBeaconEnding();
     }
 
-    if (typeof CompoundingExport !== 'undefined' && CompoundingExport.onTickBoundary) {
-        CompoundingExport.onTickBoundary();
-    }
-
     // Update UI every 10 ticks
     if (Math.floor(G.tick * 10) % 2 === 0) {
         render();

js/main.js

@@ -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/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/compounding-export.test.cjs

@@ -1,168 +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, '..');
-
-class Element {
-  constructor(tagName = 'div', id = '') {
-    this.tagName = String(tagName).toUpperCase();
-    this.id = id;
-    this.style = {};
-    this.children = [];
-    this.parentNode = null;
-    this.innerHTML = '';
-    this.textContent = '';
-    this.className = '';
-    this.dataset = {};
-    this.attributes = {};
-    this.classList = {
-      add: () => {},
-      remove: () => {},
-      contains: () => false,
-      toggle: () => false,
-    };
-  }
-  appendChild(child) { child.parentNode = this; this.children.push(child); return child; }
-  removeChild(child) {
-    const i = this.children.indexOf(child);
-    if (i >= 0) this.children.splice(i, 1);
-    if (child.parentNode === this) child.parentNode = null;
-    return child;
-  }
-  remove() { if (this.parentNode) this.parentNode.removeChild(this); }
-  setAttribute(name, value) { this.attributes[name] = value; if (name === 'id') this.id = value; }
-  querySelector() { return null; }
-  querySelectorAll() { return []; }
-  closest() { return null; }
-}
-
-function buildDom() {
-  const byId = new Map();
-  const body = new Element('body', 'body');
-  const head = new Element('head', 'head');
-  const document = {
-    body,
-    head,
-    createElement(tag) { return new Element(tag); },
-    getElementById(id) { return byId.get(id) || null; },
-    addEventListener() {},
-    removeEventListener() {},
-    querySelector() { return null; },
-    querySelectorAll() { return []; },
-  };
-  function register(el) { if (el.id) byId.set(el.id, el); return el; }
-  ['projects','alignment-ui','phase-name','phase-desc','log-entries','toast-container'].forEach(id => body.appendChild(register(new Element('div', id))));
-  return { document, window: { document, innerWidth: 1280, innerHeight: 720, addEventListener() {}, removeEventListener() {} } };
-}
-
-function loadBeacon({ endpoint = 'https://compounding.example/ingest', fetchImpl } = {}) {
-  const { document, window } = buildDom();
-  const storage = new Map();
-  storage.set('the-beacon-compounding-export-url', endpoint);
-  const fetchCalls = [];
-
-  const context = {
-    console,
-    Math,
-    Date,
-    JSON,
-    document,
-    window,
-    navigator: { userAgent: 'node' },
-    location: { reload() {} },
-    requestAnimationFrame: (fn) => fn(),
-    setTimeout: (fn) => { fn(); return 1; },
-    clearTimeout() {},
-    localStorage: {
-      getItem: (key) => (storage.has(key) ? storage.get(key) : null),
-      setItem: (key, value) => storage.set(key, String(value)),
-      removeItem: (key) => storage.delete(key),
-    },
-    fetch: async (...args) => {
-      fetchCalls.push(args);
-      if (fetchImpl) return fetchImpl(...args);
-      return { ok: true, json: async () => ({ ok: true }) };
-    },
-    Combat: { tickBattle() {}, renderCombatPanel() {}, startBattle() {} },
-    Sound: undefined,
-  };
-
-  vm.createContext(context);
-  const files = ['js/data.js', 'js/utils.js', 'js/engine.js', 'js/compounding-export.js'];
-  const source = files.map((file) => fs.readFileSync(path.join(ROOT, file), 'utf8')).join('\n\n');
-  vm.runInContext(`${source}
-log = () => {};
-showToast = () => {};
-render = () => {};
-renderPhase = () => {};
-showOfflinePopup = () => {};
-showSaveToast = () => {};
-this.__exports = { G, tick, CompoundingExport };
-`, context);
-
-  return { ...context.__exports, storage, fetchCalls };
-}
-
-function flushAsyncBoundary() {
-  return Promise.resolve().then(() => Promise.resolve()).then(() => Promise.resolve()).then(() => Promise.resolve());
-}
-
-test('buildSnapshot includes resources, project progress, trust level, and phase', () => {
-  const { G, CompoundingExport } = loadBeacon({ endpoint: '' });
-  G.code = 10;
-  G.compute = 20;
-  G.knowledge = 30;
-  G.users = 40;
-  G.impact = 50;
-  G.trust = 12;
-  G.phase = 3;
-  G.activeProjects = ['p_deploy'];
-  G.completedProjects = ['p_improved_autocoder'];
-  const snap = CompoundingExport.buildSnapshot();
-  assert.equal(snap.phase, 3);
-  assert.equal(snap.trust, 12);
-  assert.equal(snap.resources.code, 10);
-  assert.deepEqual(JSON.parse(JSON.stringify(snap.projects.active)), ['p_deploy']);
-  assert.deepEqual(JSON.parse(JSON.stringify(snap.projects.completed)), ['p_improved_autocoder']);
-});
-
-test('tick exports once when crossing a whole-second boundary', async () => {
-  const game = loadBeacon({});
-  game.G.running = true;
-  game.G.tick = 0.9;
-  game.tick();
-  await flushAsyncBoundary();
-  assert.equal(game.fetchCalls.length, 1);
-  game.tick();
-  await flushAsyncBoundary();
-  assert.equal(game.fetchCalls.length, 1);
-});
-
-test('failed export queues snapshot in localStorage', async () => {
-  const game = loadBeacon({ fetchImpl: async () => ({ ok: false }) });
-  game.G.running = true;
-  game.G.tick = 0.9;
-  game.tick();
-  await flushAsyncBoundary();
-  const queued = JSON.parse(game.storage.get('the-beacon-compounding-export-queue'));
-  assert.equal(Array.isArray(queued), true);
-  assert.equal(queued.length, 1);
-});
-
-test('successful export flushes queued snapshots before current snapshot', async () => {
-  const game = loadBeacon({});
-  game.storage.set('the-beacon-compounding-export-queue', JSON.stringify([{ sequence: 1 }, { sequence: 2 }]));
-  game.G.running = true;
-  game.G.tick = 0.9;
-  game.tick();
-  await flushAsyncBoundary();
-  const [url, opts] = game.fetchCalls[0];
-  const body = JSON.parse(opts.body);
-  assert.equal(url, 'https://compounding.example/ingest');
-  assert.equal(body.snapshots.length, 3);
-  assert.equal(body.snapshots[0].sequence, 1);
-  assert.equal(JSON.parse(game.storage.get('the-beacon-compounding-export-queue')).length, 0);
-});

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