feat: save-on-pause via visibilitychange and beforeunload (#57)

Auto-save game state when the browser tab is hidden (visibilitychange)
or closed/navigated away (beforeunload). Prevents data loss on mobile
where tab switching can kill the page without a save interval firing.

Part of epic #57 Night of Polish — Task 6: Mobile Polish.

index.html

@@ -107,11 +107,11 @@ body{background:var(--bg);color:var(--text);font-family:'SF Mono','Cascadia Code
 <h1>THE BEACON</h1>
 <div class="sub">A Sovereign AI Idle Game</div>
 </div>
-<div id="phase-bar">
+<div id="phase-bar" role="region" aria-label="Phase progress">
 <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>
 <div class="progress-wrap"><div class="progress-fill" id="phase-progress" style="width:0%"></div></div>
-<div class="progress-label"><span id="phase-progress-label">0%</span><span id="phase-progress-target">Next: Phase 2 (2,000 code)</span></div>
+<div class="progress-label" aria-live="polite"><span id="phase-progress-label">0%</span><span id="phase-progress-target">Next: Phase 2 (2,000 code)</span></div>
 <div class="milestone-row" id="milestone-chips"></div>
 </div>
 <div id="resources" role="region" aria-label="Resources" aria-live="polite">
@@ -181,7 +181,7 @@ Events Resolved: <span id="st-resolved">0</span>
 <h3>WHAT YOU ARE LEARNING</h3>
 <div id="education-text"><p class="dim">Education facts appear as you play...</p></div>
 </div>
-<div id="strategy-panel" style="margin:0 16px 16px;background:var(--panel);border:1px solid var(--border);border-radius:6px;padding:12px;border-left:3px solid var(--gold)">
+<div id="strategy-panel" role="region" aria-label="Sovereign guidance" style="margin:0 16px 16px;background:var(--panel);border:1px solid var(--border);border-radius:6px;padding:12px;border-left:3px solid var(--gold)">
 <h3>SOVEREIGN GUIDANCE (GOFAI)</h3>
 <div id="strategy-recommendation" style="font-size:11px;color:var(--gold);font-style:italic">Analyzing system state...</div>
 </div>
@@ -190,8 +190,8 @@ Events Resolved: <span id="st-resolved">0</span>
 <div id="log-entries"></div>
 </div>
 <div id="save-toast" role="status" aria-live="polite" style="display:none;position:fixed;top:16px;right:16px;background:#0e1420;border:1px solid #2a3a4a;color:#4a9eff;font-size:10px;padding:6px 12px;border-radius:4px;z-index:50;opacity:0;transition:opacity 0.4s;pointer-events:none">Save</div>
-<div id="help-btn" onclick="toggleHelp()" style="position:fixed;bottom:16px;right:16px;width:28px;height:28px;background:#0e0e1a;border:1px solid #333;color:#555;font-size:14px;border-radius:50%;cursor:pointer;display:flex;align-items:center;justify-content:center;z-index:50;font-family:inherit;transition:all 0.2s" title="Keyboard shortcuts (?)">?</div>
-<div id="help-overlay" onclick="if(event.target===this)toggleHelp()" style="display:none;position:fixed;top:0;left:0;right:0;bottom:0;background:rgba(8,8,16,0.92);z-index:80;justify-content:center;align-items:center;flex-direction:column;padding:40px">
+<div id="help-btn" onclick="toggleHelp()" role="button" tabindex="0" aria-label="Show keyboard shortcuts" style="position:fixed;bottom:16px;right:16px;width:28px;height:28px;background:#0e0e1a;border:1px solid #333;color:#555;font-size:14px;border-radius:50%;cursor:pointer;display:flex;align-items:center;justify-content:center;z-index:50;font-family:inherit;transition:all 0.2s" title="Keyboard shortcuts (?)">?</div>
+<div id="help-overlay" role="dialog" aria-modal="true" aria-label="Keyboard shortcuts help" onclick="if(event.target===this)toggleHelp()" style="display:none;position:fixed;top:0;left:0;right:0;bottom:0;background:rgba(8,8,16,0.92);z-index:80;justify-content:center;align-items:center;flex-direction:column;padding:40px">
 <div style="background:#0e0e1a;border:1px solid #1a3a5a;border-radius:8px;padding:24px 32px;max-width:420px;width:100%">
 <h3 style="color:#4a9eff;font-size:14px;letter-spacing:2px;margin-bottom:16px;text-align:center">KEYBOARD SHORTCUTS</h3>
 <div style="font-size:11px;line-height:2.2;color:#aaa">
@@ -208,10 +208,10 @@ Events Resolved: <span id="st-resolved">0</span>
 <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()" 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>
+<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>
 </div>
-<div id="drift-ending">
+<div id="drift-ending" role="dialog" aria-modal="true" aria-label="The Drift ending">
 <h2>THE DRIFT</h2>
 <p>You became very good at what you do.</p>
 <p>So good that no one needed you anymore.</p>
@@ -221,7 +221,7 @@ 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 onclick="if(confirm('Start over? The old save will be lost.')){localStorage.removeItem('the-beacon-v2');location.reload()}">START OVER</button>
+<button onclick="if(confirm('Start over? The old save will be lost.')){localStorage.removeItem('the-beacon-v2');location.reload()}" aria-label="Start over, reset all progress">START OVER</button>
 </div>
 
     <script src="js/data.js"></script>
@@ -229,15 +229,16 @@ The light is on. The room is empty."
     <script src="js/strategy.js"></script>
     <script src="js/engine.js"></script>
     <script src="js/render.js"></script>
+    <script src="js/tutorial.js"></script>
     <script src="js/main.js"></script>
   
 
-<div id="offline-popup" style="display:none;position:fixed;top:0;left:0;right:0;bottom:0;background:rgba(8,8,16,0.92);z-index:90;justify-content:center;align-items:center;flex-direction:column;text-align:center;padding:40px">
+<div id="offline-popup" role="dialog" aria-modal="true" aria-label="Welcome back, offline progress summary" style="display:none;position:fixed;top:0;left:0;right:0;bottom:0;background:rgba(8,8,16,0.92);z-index:90;justify-content:center;align-items:center;flex-direction:column;text-align:center;padding:40px">
 <div style="background:#0e0e1a;border:1px solid #1a3a5a;border-radius:8px;padding:24px 32px;max-width:400px;width:100%">
 <h3 style="color:#4a9eff;font-size:14px;letter-spacing:2px;margin-bottom:16px">WELCOME BACK</h3>
 <p style="color:#888;font-size:10px;margin-bottom:12px" id="offline-time-label">You were away for 0 minutes.</p>
 <div id="offline-gains-list" style="text-align:left;font-size:11px;line-height:1.8;margin-bottom:16px"></div>
-<button onclick="dismissOfflinePopup()" style="background:#1a2a3a;border:1px solid #4a9eff;color:#4a9eff;padding:8px 20px;border-radius:4px;cursor:pointer;font-family:inherit;font-size:11px">Continue</button>
+<button onclick="dismissOfflinePopup()" aria-label="Dismiss offline progress summary" style="background:#1a2a3a;border:1px solid #4a9eff;color:#4a9eff;padding:8px 20px;border-radius:4px;cursor:pointer;font-family:inherit;font-size:11px">Continue</button>
 </div>
 </div>
 

js/engine.js

@@ -868,7 +868,7 @@ function renderBuildings() {
     for (const amt of [1, 10, -1]) {
         const label = amt === -1 ? 'MAX' : `x${amt}`;
         const active = G.buyAmount === amt;
-        html += `<button onclick="setBuyAmount(${amt})" style="font-size:9px;padding:2px 8px;border:1px solid ${active ? '#4a9eff' : '#333'};background:${active ? '#0a1a30' : 'transparent'};color:${active ? '#4a9eff' : '#666'};border-radius:3px;cursor:pointer;font-family:inherit">${label}</button>`;
+        html += `<button onclick=\"setBuyAmount(${amt})\" style=\"font-size:9px;padding:2px 8px;border:1px solid ${active ? '#4a9eff' : '#333'};background:${active ? '#0a1a30' : 'transparent'};color:${active ? '#4a9eff' : '#666'};border-radius:3px;cursor:pointer;font-family:inherit\" aria-label=\"Set buy amount to ${label}\"${active ? ' aria-pressed=\"true\"' : ''}>${label}</button>`;
     }
     html += '</div>';
 
@@ -940,7 +940,7 @@ function renderProjects() {
     if (G.completedProjects && G.completedProjects.length > 0) {
         const count = G.completedProjects.length;
         const collapsed = G.projectsCollapsed !== false;
-        html += `<div id="completed-header" onclick="toggleCompletedProjects()" style="cursor:pointer;font-size:9px;color:#555;padding:4px 0;border-bottom:1px solid #1a2a1a;margin-bottom:4px;user-select:none">`;
+        html += `<div id=\"completed-header\" onclick=\"toggleCompletedProjects()\" role=\"button\" tabindex=\"0\" aria-expanded=\"${!collapsed}\" aria-controls=\"completed-list\" style=\"cursor:pointer;font-size:9px;color:#555;padding:4px 0;border-bottom:1px solid #1a2a1a;margin-bottom:4px;user-select:none\">`;
         html += `${collapsed ? '▶' : '▼'} COMPLETED (${count})</div>`;
         if (!collapsed) {
             html += `<div id="completed-list">`;

js/main.js

@@ -19,8 +19,10 @@ function initGame() {
 }
 
 window.addEventListener('load', function () {
-    if (!loadGame()) {
+    const isNewGame = !loadGame();
+    if (isNewGame) {
         initGame();
+        startTutorial();
     } else {
         render();
         renderPhase();
@@ -97,3 +99,13 @@ window.addEventListener('keydown', function (e) {
         saveGame();
     }
 });
+
+// Save-on-pause: auto-save when tab is hidden or closed (#57 Mobile Polish)
+document.addEventListener('visibilitychange', function () {
+    if (document.hidden) {
+        saveGame();
+    }
+});
+window.addEventListener('beforeunload', function () {
+    saveGame();
+});

js/render.js

@@ -31,8 +31,8 @@ function renderAlignment() {
                 <div style="color:#f44336;font-weight:bold;margin-bottom:6px">ALIGNMENT EVENT: The Drift</div>
                 <div style="font-size:10px;color:#aaa;margin-bottom:8px">An optimization suggests removing the human override. +40% efficiency.</div>
                 <div class="action-btn-group">
-                    <button class="ops-btn" onclick="resolveAlignment(true)" style="border-color:#f44336;color:#f44336">Accept (+40% eff, +Drift)</button>
-                    <button class="ops-btn" onclick="resolveAlignment(false)" style="border-color:#4caf50;color:#4caf50">Refuse (+Trust, +Harmony)</button>
+                    <button class=\"ops-btn\" onclick=\"resolveAlignment(true)\" style=\"border-color:#f44336;color:#f44336\" aria-label=\"Accept alignment event, gain 40 percent efficiency but increase drift\">Accept (+40% eff, +Drift)</button>
+                    <button class=\"ops-btn\" onclick=\"resolveAlignment(false)\" style=\"border-color:#4caf50;color:#4caf50\" aria-label=\"Refuse alignment event, gain trust and harmony\">Refuse (+Trust, +Harmony)</button>
                 </div>
             </div>
         `;
@@ -83,7 +83,8 @@ function exportSave() {
     const ts = new Date().toISOString().slice(0, 10);
     a.download = `beacon-save-${ts}.json`;
     a.click();
-    URL.revokeObjectURL(url);
+    // Delay revoke to avoid race — some browsers need time to start the download
+    setTimeout(() => URL.revokeObjectURL(url), 1000);
     log('Save exported to file.');
 }
 

js/tutorial.js

@@ -0,0 +1,248 @@
+// ============================================================
+// THE BEACON - Tutorial / Onboarding
+// First-time player walkthrough (4 screens + skip option)
+// ============================================================
+
+const TUTORIAL_KEY = 'the-beacon-tutorial-done';
+
+const TUTORIAL_STEPS = [
+    {
+        title: 'THE BEACON',
+        body: 'Build an AI from scratch.\n\nWrite code. Train models. Deploy to the world.\nSave lives.',
+        icon: '🏠',
+        tip: 'A sovereign AI idle game'
+    },
+    {
+        title: 'WRITE CODE',
+        body: 'Click WRITE CODE or press SPACE to generate code.\n\nClick fast for combo bonuses:\n  10× combo → bonus ops\n  20× combo → bonus knowledge\n  30×+ combo → bonus code',
+        icon: '⌨️',
+        tip: 'This is your primary action'
+    },
+    {
+        title: 'BUILD & RESEARCH',
+        body: 'Buy Buildings for passive production.\nThey generate resources automatically.\n\nResearch Projects appear as you progress.\nThey unlock powerful multipliers and new systems.',
+        icon: '🏗️',
+        tip: 'Automation is the goal'
+    },
+    {
+        title: 'PHASES & PROGRESS',
+        body: 'The game has 6 phases, from "The First Line" to "The Beacon."\n\nEach phase unlocks new buildings, projects, and challenges.\n\nYour AI grows from a script... to something that matters.',
+        icon: '📊',
+        tip: 'Watch the progress bar at the top'
+    },
+    {
+        title: 'YOU\'RE READY',
+        body: 'Buildings produce while you think.\nProjects multiply your output.\nKeep harmony high. Avoid the Drift.\n\nThe Beacon is waiting. Start writing.',
+        icon: '✦',
+        tip: 'Press ? anytime for keyboard shortcuts'
+    }
+];
+
+function isTutorialDone() {
+    try {
+        return localStorage.getItem(TUTORIAL_KEY) === 'done';
+    } catch (e) {
+        return true; // If localStorage is broken, skip tutorial
+    }
+}
+
+function markTutorialDone() {
+    try {
+        localStorage.setItem(TUTORIAL_KEY, 'done');
+    } catch (e) {
+        // silent fail
+    }
+}
+
+function createTutorialStyles() {
+    if (document.getElementById('tutorial-styles')) return;
+    const style = document.createElement('style');
+    style.id = 'tutorial-styles';
+    style.textContent = `
+#tutorial-overlay {
+    position: fixed;
+    top: 0; left: 0; right: 0; bottom: 0;
+    background: rgba(8, 8, 16, 0.96);
+    z-index: 300;
+    display: flex;
+    justify-content: center;
+    align-items: center;
+    animation: tutorial-fade-in 0.4s ease-out;
+}
+@keyframes tutorial-fade-in {
+    from { opacity: 0 } to { opacity: 1 }
+}
+#tutorial-card {
+    background: #0e0e1a;
+    border: 1px solid #1a3a5a;
+    border-radius: 10px;
+    padding: 32px 36px;
+    max-width: 420px;
+    width: 90%;
+    text-align: center;
+    animation: tutorial-slide-up 0.5s ease-out;
+    position: relative;
+}
+@keyframes tutorial-slide-up {
+    from { transform: translateY(20px); opacity: 0 }
+    to { transform: translateY(0); opacity: 1 }
+}
+#tutorial-card .t-icon {
+    font-size: 36px;
+    margin-bottom: 12px;
+    display: block;
+}
+#tutorial-card .t-title {
+    color: #4a9eff;
+    font-size: 16px;
+    font-weight: 700;
+    letter-spacing: 3px;
+    margin-bottom: 12px;
+    font-family: inherit;
+}
+#tutorial-card .t-body {
+    color: #999;
+    font-size: 11px;
+    line-height: 1.9;
+    margin-bottom: 20px;
+    white-space: pre-line;
+    font-family: inherit;
+    text-align: left;
+}
+#tutorial-card .t-tip {
+    color: #555;
+    font-size: 9px;
+    font-style: italic;
+    margin-bottom: 20px;
+    letter-spacing: 1px;
+    font-family: inherit;
+}
+#tutorial-dots {
+    display: flex;
+    gap: 6px;
+    justify-content: center;
+    margin-bottom: 18px;
+}
+#tutorial-dots .t-dot {
+    width: 6px;
+    height: 6px;
+    border-radius: 50%;
+    background: #1a1a2e;
+    transition: background 0.3s;
+}
+#tutorial-dots .t-dot.active {
+    background: #4a9eff;
+    box-shadow: 0 0 6px rgba(74, 158, 255, 0.4);
+}
+#tutorial-btns {
+    display: flex;
+    gap: 8px;
+    justify-content: center;
+}
+#tutorial-btns button {
+    font-family: inherit;
+    font-size: 11px;
+    padding: 8px 20px;
+    border-radius: 4px;
+    cursor: pointer;
+    transition: all 0.15s;
+}
+#tutorial-next-btn {
+    background: #1a2a3a;
+    border: 1px solid #4a9eff;
+    color: #4a9eff;
+}
+#tutorial-next-btn:hover {
+    background: #203040;
+    box-shadow: 0 0 12px rgba(74, 158, 255, 0.2);
+}
+#tutorial-skip-btn {
+    background: transparent;
+    border: 1px solid #333;
+    color: #555;
+}
+#tutorial-skip-btn:hover {
+    border-color: #555;
+    color: #888;
+}
+    `;
+    document.head.appendChild(style);
+}
+
+function renderTutorialStep(index) {
+    const step = TUTORIAL_STEPS[index];
+    if (!step) return;
+
+    let overlay = document.getElementById('tutorial-overlay');
+    if (!overlay) {
+        overlay = document.createElement('div');
+        overlay.id = 'tutorial-overlay';
+        document.body.appendChild(overlay);
+    }
+
+    const isLast = index === TUTORIAL_STEPS.length - 1;
+
+    // Build dots
+    let dots = '';
+    for (let i = 0; i < TUTORIAL_STEPS.length; i++) {
+        dots += `<div class="t-dot${i === index ? ' active' : ''}"></div>`;
+    }
+
+    overlay.innerHTML = `
+        <div id="tutorial-card">
+            <span class="t-icon">${step.icon}</span>
+            <div class="t-title">${step.title}</div>
+            <div class="t-body">${step.body}</div>
+            <div class="t-tip">${step.tip}</div>
+            <div id="tutorial-dots">${dots}</div>
+            <div id="tutorial-btns">
+                <button id="tutorial-skip-btn" onclick="closeTutorial()">Skip</button>
+                <button id="tutorial-next-btn" onclick="${isLast ? 'closeTutorial()' : 'nextTutorialStep()'}">${isLast ? 'Start Playing' : 'Next →'}</button>
+            </div>
+        </div>
+    `;
+
+    // Focus the next button so Enter works
+    const nextBtn = document.getElementById('tutorial-next-btn');
+    if (nextBtn) nextBtn.focus();
+}
+
+let _tutorialStep = 0;
+
+function nextTutorialStep() {
+    _tutorialStep++;
+    renderTutorialStep(_tutorialStep);
+}
+
+// Keyboard support: Enter/Right to advance, Escape to close
+document.addEventListener('keydown', function tutorialKeyHandler(e) {
+    if (!document.getElementById('tutorial-overlay')) return;
+    if (e.key === 'Enter' || e.key === 'ArrowRight') {
+        e.preventDefault();
+        if (_tutorialStep >= TUTORIAL_STEPS.length - 1) {
+            closeTutorial();
+        } else {
+            nextTutorialStep();
+        }
+    } else if (e.key === 'Escape') {
+        e.preventDefault();
+        closeTutorial();
+    }
+});
+
+function closeTutorial() {
+    const overlay = document.getElementById('tutorial-overlay');
+    if (overlay) {
+        overlay.style.animation = 'tutorial-fade-in 0.3s ease-in reverse';
+        setTimeout(() => overlay.remove(), 280);
+    }
+    markTutorialDone();
+}
+
+function startTutorial() {
+    if (isTutorialDone()) return;
+    createTutorialStyles();
+    _tutorialStep = 0;
+    // Small delay so the page renders first
+    setTimeout(() => renderTutorialStep(0), 300);
+}