docs: update README file map for split runtime (#169)

README.md documented game.js as a single-file core engine, but the
runtime was split into 10 modules under js/. Updated the file map
to reflect the current architecture.

README.md

@@ -104,8 +104,18 @@ This game is a **decision simulator** for our actual work.
 
 ## Files
 
-- `index.html` — Game UI
-- `game.js` — Core engine (tick loop, buildings, projects, events)
+- `index.html` — Game UI + script loader
+- `js/` — Split runtime (10 modules):
+  - `data.js` — Game data, project/upgrade/event definitions
+  - `utils.js` — Shared helpers
+  - `combat.js` — Combat and threat resolution
+  - `strategy.js` — Strategic decision logic
+  - `sound.js` — Audio engine
+  - `engine.js` — Core tick loop and state management
+  - `render.js` — DOM rendering and UI updates
+  - `tutorial.js` — Tutorial/onboarding flow
+  - `dismantle.js` — Dismantle/teardown mechanics
+  - `main.js` — Entry point, init, and game start
 - `DESIGN.md` — Full design document with narrative arc and mechanics
 - `README.md` — This file
 

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;

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;

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