feat: add first-time player tutorial walkthrough

Part of #57 — Task 4: Tutorial & Onboarding

- 5 click-through screens introducing game concepts (code, buildings,
  research, phases, keyboard shortcuts)
- Skip button on every screen, keyboard support (Enter/Escape/arrows)
- Stores completion in localStorage — only shows once for new players
- Matches existing visual style (dark theme, accent colors, monospace)
- Start Playing button on final screen with shortcut hint (? overlay)

README.md

@@ -118,7 +118,3 @@ This is a static HTML/JS game. Just open `index.html` in a browser.
 *The Beacon is not about making the most paperclips.  
 It is about keeping the light on for one person in the dark.  
 Everything else is just infrastructure.*
-
-
----
-Merged by AI

index.html

@@ -208,7 +208,7 @@ 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()" 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>
+<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>
 </div>
 </div>
 <div id="drift-ending">
@@ -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 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>
+<button 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>
@@ -229,6 +229,7 @@ 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>
   
 
@@ -237,7 +238,7 @@ The light is on. The room is empty."
 <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()" aria-label="Continue playing" 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()" 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/main.js

@@ -19,8 +19,10 @@ function initGame() {
 }
 
 window.addEventListener('load', function () {
-    if (!loadGame()) {
+    const isNewGame = !loadGame();
+    if (isNewGame) {
         initGame();
+        startTutorial();
     } else {
         render();
         renderPhase();

js/render.js

@@ -83,8 +83,7 @@ function exportSave() {
     const ts = new Date().toISOString().slice(0, 10);
     a.download = `beacon-save-${ts}.json`;
     a.click();
-    // Delay revoke to avoid race — some browsers need the URL alive during download
-    setTimeout(() => URL.revokeObjectURL(url), 1000);
+    URL.revokeObjectURL(url);
     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);
+}

js/utils.js

@@ -193,7 +193,44 @@ function spellf(n) {
     return parts.join(' ') || 'zero';
 }
 
-// Export/import are defined in render.js (file-based approach)
+// === EXPORT / IMPORT ===
+function exportSave() {
+    const raw = localStorage.getItem('the-beacon-v2');
+    if (!raw) { 
+        showToast('No save data to export.', 'info');
+        return; 
+    }
+    navigator.clipboard.writeText(raw).then(() => {
+        showToast('Save data copied to clipboard.', 'info');
+    }).catch(() => {
+        // Fallback: select in a temporary textarea
+        const ta = document.createElement('textarea');
+        ta.value = raw;
+        document.body.appendChild(ta);
+        ta.select();
+        document.execCommand('copy');
+        document.body.removeChild(ta);
+        showToast('Save data copied to clipboard (fallback).', 'info');
+    });
+}
+
+function importSave() {
+    const input = prompt('Paste save data:');
+    if (!input || !input.trim()) return;
+    try {
+        const data = JSON.parse(input.trim());
+        // Validate: must have expected keys
+        if (typeof data.code !== 'number' || typeof data.phase !== 'number') {
+            showToast('Invalid save data: missing required fields.', 'event');
+            return;
+        }
+        localStorage.setItem('the-beacon-v2', input.trim());
+        showToast('Save data imported — reloading', 'info');
+        setTimeout(() => location.reload(), 800);
+    } catch (e) {
+        showToast('Invalid save data: not valid JSON.', 'event');
+    }
+}
 
 function getBuildingCost(id) {
     const def = BDEF.find(b => b.id === id);